Add all documentation for contributing documentation

[DragaDoncila]

As discussed at the last docs working group meeting, this PR captures the latest changes to all "docs about contributing docs".

There are five main documents which together should help anyone new to napari.org contribute documentation.

• Contributor's overview
• Tutorial template
• How to template
• Preparing your notebook tutorial
• Submit "git-free" PR how-to

I've opened this PR here as opposed to in napari/napari so that we can preview it easily. To preview, checkout this branch and use Jeremy's guide to set up your dev environment.

I've placed this "Documentation" section at the top level for now (I actually don't know how to make a subsection?), purely so that we can check what it's like to browse these documents, and whether they are cohesive.

Feedback needed:

• Is it cohesive, and easy to browse?
• Can a new user find what they need regardless of which document they first start in?
• Is any content missing?

You're of course welcome to leave any feedback on individual document content as well (note that some links don't yet exist because I don't know exactly where we'll put this), however note that ultimately this PR will not be merged - each document will be contributed in a separate PR to napari/napari once we're happy with the overall structure.

Pinging @GenevieveBuckley because I know you had concerns about how this all would tie together. Also pinging @melissawm who I don't think has seen these for a while.

[GenevieveBuckley]

The index.md needs restructuring. Our index page needs to be a one page how to guide, with numbered steps so that if you follow them you go from having nothing, to having a useful docs PR submitted to napari.

Right now this is mixed in and buried by explanation about the diataxis framework, and how we like to organize files in napari. That's nice to know, but it's not a concrete step in the how to guide, so we need to move that to make things less confusing.

I'm imagining this type of structure:

• main page: how to guide for contributing to the napari docs (this doesn't exist just yet, I'd say bits of it are in the second half of index.md)
  • subpage: template document(s) for users to download (currently this is tutorial_template & how_to_template)
  • subpage: how to use jupytext, assuming we can't fit it in the template itself, that would be simpler (currently this is in prepare_notebook_tutorial)
  • subpage: how to categorize documentation, and where differnt types live on the repository (currently this is index.md)

[GenevieveBuckley]

I imagine the main page steps would be roughly these:

How to write a tutorial or how-to guide for napari

1. Setup: you need to have napari + jupyter installed
   • link to napari user installation docs (clickable link)
2. Download this template (clickable link)
   • Don't know which template you need? Read this guide (clickable link)
3. Open the template notebook with jupyter and add your content
   • Explanation of nbscreenshot and other utility functions (either in the template document, or in a separate document linked to from here)
4. Quality check: does your finished notebook run end to end without errors? ("Restart and Run All" cells). This includes any necessary data downloading, etc.
5. Preparing to upload. Using jupytext to convert your finished notebook into the right format
6. Making a pull request to the napari docs
   • Where to put your new documentation page in the repository
   • Mechanics of how to open a PR (links to github docs, etc)
   • How to see a preview of your documentation page online
7. Iteration based on reviewer feedback (I really like that this was included as a step in some of Draga's work)

[GenevieveBuckley]

More minor points I'm happy for other people to disagree with, just throwing these out there:

• Both the how_to_template and tutorial_template documents seem almost entirely identical. I think only some of the headins are slightly different? Maybe these could be combined? (I know I previously said some duplication was ok, and it is, but this looks like quite a lot of duplication so maybe there is an opportunity there)
• I personally would probably prefer it if most of the "prepare_notebook_tutorial" content was included with the template. I feel like it would make it much more likely for people to see it exists. It's much easier to copy a cell and make a small edit if it's already in the notebook (especially for things like tagging cells, where you'd otherwise have to dig around for the right menu if you're not familiar with making them)

[DragaDoncila]

@GenevieveBuckley @melissawm I've made the updates we discussed at the docs wg meeting last week. I'd appreciate if you could have a look and see if we prefer this direction.

One thing I can't figure out is how to make the "Download this template" link an actual file download button? It seems like it should be easy but I've never done it in markdown...

[GenevieveBuckley]

One thing I can't figure out is how to make the "Download this template" link an actual file download button? It seems like it should be easy but I've never done it in markdown...

You can use the markdown link syntax, like this:

[Click here to download this template](https://link-to-download-file)

[GenevieveBuckley]

Thanks @DragaDoncila! This is looking much more streamlined and easier to use.

[DragaDoncila]

@GenevieveBuckley I think this is now ready for a final pass before we close and reopen in napari/napari to actually contribute it. However, it would be nice to get a review from someone outside the docs working group - I don't think we've really shared this work with the community.

@sofroniewn @jni I'd love if you could look through this PR - these documents would be all the content available for users wanting to contribute documentation. It's in this PR so it can be viewed as a whole, and so that it can be easily previewed with the napari.org theme.

• Do you have any big concerns with the flow of the content?
• Is anything glaringly missing?

[DragaDoncila]

For the main PR are we going to use the trick of uploading the images in the PR comments then linking to the images through the web (rather than add them directly to the repo). This will keep size down in the main repo.

@sofroniewn yes and thank you for reminding me! I've also added text to that effect to the instructions for users

Also maybe some comments that we don't want data added to the main repo. Maybe that's obvious, but it doesn't hurt to comment as such.

Agreed. I've flagged this now in the pre-requisites list of the docs template.

[GenevieveBuckley]

I notice this PR is still marked as a draft, @DragaDoncila are you waiting on a few things here, or is this mostly ready (it seems mostly ready to me, my understanding is that all the review comments have been addressed & we could probably merge this whenever you'd like)

[DragaDoncila]

@GenevieveBuckley this is still in draft mode because I'm waiting on some of the dust to settle from the TOC reorg before moving this PR into napari/napari where it actually belongs - I only opened it here to give us quick access to previews.

[GenevieveBuckley]

One extra point, is that images should have meaningful alt-text. This should be communicated to users, and also included as a reviewer checklist item.

We're working on a mechanism for alt-text with nbscreenshot here: https://github.com/napari/napari/pull/3825#issuecomment-996040101 This is all a little bit in flux at the moment, so it's fine to make a follow up PR if needed. Just flagging it for you now.

[psobolewskiPhD]

@DragaDoncila Some good things here, like the PR online part and some stuff is already more or less there at: https://napari.org/dev/developers/documentation/index.html Maybe worth trying to port some of this to https://github.com/napari/docs ? Eitherway, this will need to be closed.

[psobolewskiPhD]

As per my comment above, this won't be merged here so closing. I made an issue over at napari/docs to look into porting stuff from this PR though: https://github.com/napari/docs/issues/330