Reorg of the Usage section of the docs

[melissawm]

References and relevant issues

N/A

Description

At the napari hackathon @ gloBIAS, we had the chance to discuss the docs organization with a few users and came up with ideas for potential improvements to our Usage section. We also discussed some changes to our API docs, but those will be handled separately.

This is a first very rough draft that is clearly incomplete, but I wanted to stash it somewhere so the work can continue.

EDIT: This is now ready for review. It only touches the first sections of the user guide but I think this is reasonable for now. This was discussed at the docs meeting this week (nov 20/21).

[psobolewskiPhD]

This is really great! 😍
Huge fan of breaking out the Layers into its own thing! This PR is the real closer to #42 😉

One thing that stand out to me:
Getting started > Open images is empty -- just a placeholder for now? Maybe we should copy paste something into it and flag it as a followup?
(the quickstart open an image could use a spruce up too probably)

[brisvag]

Love this work @melissawm! Much better than main :) Some thoughts:

• Did we come up with a better name for the Features highlights section in the end?
• I'd rename napari tutorial to something like case studies or in depth examples or walkthroughs. I'm also not sure if we want that there or lower down, but maybe we already discussed this?

[DragaDoncila]

as mentioned in docs meeting, I love this reorg ❤️ I dropped by because I noticed in the napari help menu we link to some of these guides, and I wanted to flag it in case we need to update any of those URLs. I don't think we do? Because it looks like it links to the file and we don't move the file. But just wanted to flag it and ask.

[melissawm]

Getting started > Open images is empty -- just a placeholder for now? Maybe we should copy paste something into it and flag it as a followup?

Exactly! I can remove this from the ToC for now but we do think this is important, and was something users brought up during the hackathon.

@DragaDoncila I will verify the help menu - good callout, I think we should be fine but we should check anyways. Worst case scenario we can also include redirects.

EDIT: Only the Getting Started link needs to change to "https://napari.org/{VERSION}/getting_started/start_index.html", here's the PR: napari/napari#8455

[willingc]

@melissawm Looks great. Not sure if in or out of scope, but I think we can shorten a few headings:

• Shorten 'napari tutorials' to 'Tutorials'
• Shorten 'napari workshops' to 'Workshops'
• Shorten 'Layers User Guide' to 'Using layers'

[melissawm]

@willingc Thanks Carol! For tutorials and workshops I'm 💯 , for "Using layers" that's what we had before, and @TimMonko brought up something he saw on a talk which we agreed on, which is having the subject (layers in this case) be upfront in these titles so readers can skim better (Tim would you mind dropping a link here?)

However I'm not opposed to finding a shorter title if you have ideas! Maybe just "Layers guide"?

[willingc]

Layers Guide would be great. Thanks @melissawm and @TimMonko

[willingc]

Thanks @melissawm

[willingc]

@melissawm Maybe change the card to match Layers guide too. Same with Quickstart and Workshops.

[Czaki]

I like this changes

[melissawm]

Updated!

[guiwitz]

Hi @melissawm. This looks great! BTW I created the docs locally using the pixi instructions and it worked really easily even though I'm not really a pixi user. I tried to go through the docs systematically and here are a few things I noticed:

• Plugins: Plugins are mentioned in multiple places but there's never a paragraph to explain what they are or a link to the actual "Finding and installing plugins" page. For example in the Quickstart they are mentioned multiple times but the links only send to the hub or actual plugins pages. Same for the "Getting Started" section. For example plugins are mentioned in the in "Install" section but just to say that depending on how you install napari, certain plugins might not work. I have the impression a new user would go through these docs and not really understand this. I think plugins are not just some kind of optional additional thing you can do, but actually essential, e.g. they are required to open most non-tiff microscopy images. So my suggestion would be:
  • in the "Quickstart", add a section "Plugins" quickly explaining what they are and sending readers to the actual plugin section
  • in the "Getting Started -> Install napari" section add a specific part about installing plugins. I feel basic napari installation and plugin installation are tightly linked, so it would make sense to have it there. Again, no need to repeat content, but liking to the plugin page with minimum context would be sufficient.
• Beginners: I still think that at the moment the introductory material contains too much code. The Quickstart has code, the Tour of the napari viewer has code etc. I fear this will turn away beginners who don't regularly code. I understand the goal of not duplicating information (e.g. showing how to use the layer list interactively and programmatically) but I think it would be useful to have at least a no-code simplified intro. Just as a simple example: if a user just wants to visualize some data in 3D (for which napari is really good), currently the 2d/3d toggling relies on importing data with code, while one could just import the demo cells3d image, show the 2D version, show the button, show the 3d version.
• Open image: I'm happy to have a go at this if nobody else is working on it. Maybe in a new PR once this one is merged?

[brisvag]

All great points!

Open image: I'm happy to have a go at this if nobody else is working on it. Maybe in a new PR once this one is merged?

You can get started already if you want 😉

[melissawm]

Thank you so much @guiwitz ! Excellent points - I will try to address them in my next commit 😄

[Czaki]

bump