Getting started with PAWS tutorial is complete: https://hub.paws.wmcloud.org/user/SRodlund_%28WMF%29/notebooks/PAWS-Tutorial.ipynb

Suggestions for improvements, edits, and additions are appreciated!

Public link: https://public.paws.wmcloud.org/User:SRodlund_(WMF)/PAWS-Tutorial.ipynb

Overall I really like it! My edit notes follow, and may look like a lot of complaints, but really this is great and they are mostly nits.

• PAWS (A Web Shell)
  • The "Write and run resource light scripts and bots to help support Wikimedia projects" link in the introduction links to https://hub.paws.wmcloud.org/user/SRodlund_%28WMF%29/notebooks/Using-Pywikibot-with-Paws.ipynb#Documentation rather than https://public.paws.wmcloud.org/User:SRodlund_(WMF)/PAWS-Tutorial.ipynb#Documentation (the former is only visible when authenticated to PAWS as @srodlund)
• Quickstart
  • Adding a target="_blank" to the "Launch PAWS" link might be a good idea. Generally I'm against forcing where links open, but in the case of a tutorial it can be nice to keep the user's place in the tutorial itself when providing them with a "go to this place and do X" kind of instruction.
  • "Voila" is probably not a great word choice for a english langauge document that will have non-native readers. Slightly better would be the proper French spelling of voilà, but there are probably other easier to parse phrases that would give a similar "it is magic!" feel without crossing fuzzy linguistic boundaries.
• Finding your way around the control panel
  • 'The "Runnng" tab' is misspelled.
  • "As you can see, you have the option to run several different kernals" -- misspelling of "kernels". This is also jargon, so I would expect either a short inline explanation or a link to https://jupyter.readthedocs.io/en/latest/projects/kernels.html nearby.
• Cells
  • "Pay attention to the order of the cells of executable code and the order that you run them in." -- awkward sentence. The rest of the paragraph seems more clear to me. Maybe replace with something like "The order of the cells in the notebook and the order that they are run in is important."
• Title your notebook
  • "When naming your notebook, do not include spaces in the title. Otherwise, you will not be able to share it with others using the public link. For example, use: a-brand-new-notebook instead of A Brand New Notebook" -- this bug has been fixed! https://public.paws.wmcloud.org/User:BDavis_(WMF)/Hello%20world.ipynb
• Fork a notebook
  • The ?format=raw example URL is a live link to a 404 page. Probably better to mark it up as literal text like the example link in the step above it.
• Best practices
  • I don't know that I've seen the phrase "the Open Source Wikimedia community" anywhere before. Does this mean what is more often called the Wikimedia technical community or something else?
  • "Don't leave spaces in the title of your notebook; otherwise, you won't be able to access it through a public link." -- fixed bug, spaces are ok on the current PAWS cluster.

This is way better than anything we've had, and I really wish I'd had it when I started and first looked at PAWS :)

A couple nits I noticed:

• PAWS (A Web Shell)
  • PAWS supports makes it easier for volunteers along the spectrum to work in technical spaces and make contributions Wikimedia's technical projects. <-- looks like both "supports" and "makes it easier for" were written by mistake instead of one or the other
  • A couple of the useful links in this section mostly use the old URL scheme for paws public. That's ok, but it does require an unnecessary redirect to the new scheme.

Also, in the "Best Practices", it would be awesome if we mentioned that people should understand that even though some files can be hidden, we do not guarantee that anything "secret" on PAWS is secure. Therefore, we highly recommend that private ssh keys not be stored there, and people use ssh clients (phone or computer based) instead of the PAWS terminal as an ssh client. I would like to add that because we discovered that someone does this recently (and that others have before), and while this may be necessary for some people with restricted technology access, we don't recommend it...also probably best to remove a key when you are done with it, if you do this. PAWS should be thought of as public.

Thanks @bd808 and @Bstorm! I integrated these changes. If you see anything else let me know. My spelling and grammar check don't work in the Python 3 notebooks so I try my best but it's totally possible there are some errors.

In T261585#6467323, @srodlund wrote:

Thanks @bd808 and @Bstorm! I integrated these changes. If you see anything else let me know. My spelling and grammar check don't work in the Python 3 notebooks so I try my best but it's totally possible there are some errors.

A few more nits I noticed in the new version:

• PAWS (A Web Shell)
  • The link for "Write and run resource light scripts and bots to help support Wikimedia projects" is not rendering correctly. It looks to me like the ) in @srodlund's SUL user name is breaking the markdown link syntax. Try using https://public.paws.wmcloud.org/User:SRodlund_%28WMF%29/PAWS-Tutorial.ipynb#Documentation in the source.
• Finding your way around the control panel
  • The "Running" tab lets you see which terminals and notebooks you have running, what kernal they are on, and their status. -- "kernel" jargon word is misspelled

Ah!

1. Good catch. Actually, there was an extra space between the bracket and the first ( . Fixed!
2. Ah. How did I miss that? Fixed!

In T261585#6468215, @srodlund wrote:

1. Good catch. Actually, there was an extra space between the bracket and the first ( . Fixed!

I'm still seeing the parsing failure on the public view:

The source line now reads "* [Write and run resource light scripts and bots to help support Wikimedia projects](https://public.paws.wmcloud.org/User:SRodlund_(WMF)/PAWS-Tutorial.ipynb#Documentation) (Note here that for heavy duty or scheduled jobs folks should be using [Toolforge](https://wikitech.wikimedia.org/wiki/Portal:Toolforge).)\n",. I'm pretty sure that the markdown parser is seeing the unescaped ) in User:SRodlund_(WMF) as the end of the [label](url) link syntax.

Assuming this is being worked on per last comments, hence setting quarterly tag.

I've been working on mocking up a new landing page for PAWS and creating pages that explain what it is, why (or why not) to use it and that feature the new tutorials I'm working on. If you have a chance to take a look, I would appreciate some feedback. :-)

Audience
There is a three-fold audience for these pages; for the documentation, I am focusing most on the first audience -- which I believe will cover the others as well.

1. Newcomers to the Wikimedia technical community -- automated tasks many newcomers can do to contribute to Wikimedia Projects
2. Data Scientists and researchers -- Jupyter is the computational notebook of choice for data scientists
3. Existing contributors -- PAWS is another good tool, with solid support, that they can use to contribute to Wikimedia Projects

Purpose
My goal is to keep the pages uncomplicated and move folks toward the notebook based tutorials, which I feel will be more useful for the practical use of PAWS. I feel like the individual pages on Wiktech can use some more work though.

Current pages

• https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/About_Jupyter_notebooks_hosted_on_PAWS -- A high-level overview of PAWS and Jupyter notebooks with the goal of informing and helping folks decide "Is this the right Tool?"
• https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/Getting_started_with_PAWS -- A quick start guide with a link to a comprehensive tutorial on using the PAWS control panel and interface
• https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/PAWS_and_Pywikibot -- A short description of Pywikibot and Paws with a link to a more comprehensive tutorial which will cover this more in detail and walk users through using Pywikibot in a Python 3 notebook and PAWS terminal with a few very basic tasks users can perform
• https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/PAWS_examples_and_recipes - a page that lists examples of different types of pages of notebooks (so users can envision what they can do with the tool) and Coming Soon -- a set of notebook based recipes for common tasks that can be performed using Pywikbot with PAWS
• https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/PAWS_maintenance_and_administration -- links to maintenance and administration documentation

Help!

This is obviously a work in progress, so I'm sure it is missing plenty and needs improvement to design and content, but I think it's a good time to gather some thoughts and feedback.

• If you were a newcomer would you have a basic understanding of what PAWS is by visiting these pages?
• Do the pages have enough information? (Especially, the PAWS Pywikibot page). I'm trying to avoid information overload and get folks onto the tutorials where they can use the information to explore PAWS right away.
• Would you like to see pages or sections focusing toward specific audiences newcomers, data scientists & researchers, more experienced contributors, etc?
• What's missing? What more would you like to see?
• What is just not good?

In T261585#6487712, @srodlund wrote:

• If you were a newcomer would you have a basic understanding of what PAWS is by visiting these pages?

Yes! I do get the basic understanding of what PAWS is after visiting these pages. I've made a few minor edits to some pages :)

• Do the pages have enough information? (Especially, the PAWS Pywikibot page). I'm trying to avoid information overload and get folks onto the tutorials where they can use the information to explore PAWS right away.

I think a tutorial like this seems to be super valuable. It might be a lot of work for now, but in the future, it would be nice to have some more examples like that around datasets, using wiki replicas & databases, APIs, etc. I see that we have added some examples here https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/PAWS_examples_and_recipes#Example_notebooks, but tutorials would be super useful for newcomers. I also noticed that the PAWS and Pywikibot tutorial is currently linked from a Wikitech page, which is simply adding another step to get to the tutorial, and both now have duplicate information. Perhaps, you could consider not using the page at all. I am happy to test out the PAWS + Pywikibot notebook when it is complete.

• Would you like to see pages or sections focusing toward specific audiences newcomers, data scientists & researchers, more experienced contributors, etc?

Yes, there could be more documentation for data scientists and researchers as they rely on notebooks a lot. And, other use cases that I've highlighted above..

Some nit picks:

• Not sure what "resource light bots" & "resource light scripts" means here: https://wikitech.wikimedia.org/wiki/User:SRodlund/About_Jupyter_notebooks_hosted_on_PAWS
• I'm wondering if there is no another way to fork someone's notebook without downloading it: https://wikitech.wikimedia.org/wiki/User:SRodlund/PAWS_(staging)/pagedesign/Getting_started_with_PAWS#Fork
• PAWS examples and recipes: a bit unclear what https://public.paws.wmcloud.org/36582847/?C=M&O=D is for. The notebooks that we see here is that all we have in public?

Thanks for the feedback @srishakatux. I've integrated some, and think some will have to make more time for additional updates.

I moved the new PAWS docs from staging to the Main space: https://wikitech.wikimedia.org/wiki/PAWS

These pages can still use improvement. So feel free to leave feedback here or on the talk pages or be bold and edit if you see a glaring error :-)