Reorg of the Usage section of the docs #881

melissawm · 2025-10-30T00:21:23Z

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 · 2025-11-25T01:45:51Z

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 · 2025-11-25T11:59:54Z

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 · 2025-11-26T03:24:57Z

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 · 2025-11-29T18:00:27Z

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 · 2025-11-29T22:23:57Z

@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 · 2025-11-29T23:31:17Z

@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 · 2025-11-30T16:31:35Z

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

willingc

Thanks @melissawm

willingc · 2025-11-30T16:33:34Z

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

docs/tutorials/cell_tracking.md

Czaki

I like this changes

melissawm · 2025-12-03T14:19:59Z

Updated!

guiwitz · 2025-12-05T08:21:40Z

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 · 2025-12-05T09:36:42Z

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 · 2025-12-05T12:19:28Z

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

Czaki · 2025-12-16T11:04:21Z

bump

melissawm · 2025-12-20T22:37:01Z

Hello, folks! I tried addressing all the comments above. It may not be perfect but I'd like to merge this for 0.7.0 and we can continue improving in the meantime. I don't know how to solve the codespell errors though - the release notes seem to have some kind of formatting error at the source?

Anyway, @guiwitz if you can take a look soon that would be awesome. There is certainly room for improvements in all of these changes but at least we have a starting point.

Thanks!

psobolewskiPhD · 2025-12-22T20:47:11Z

docs/getting_started/quick_start.md

 (napari-quick-start)=

-# Quick start
+# Quickstart


My dictionary and my wife suggest this should be reverted to two words. cc: @napari/copy

Suggested change

# Quickstart

# Quick start

@psobolewskiPhD Both versions are now acceptable. Quickstart has become the norm for technical guides, while quick start means beginning quickly. I'm fine with either though would lean toward one word.

Yeah I've been corrected in other projects where people made me go with the one-word version. I'd prefer keeping it !

docs/getting_started/quick_start.md

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>

melissawm · 2026-01-06T20:39:13Z

I think I got it all. Still trying to figure out what to do with the release notes that are causing the codespell error, but the cards and tabs are now working. Thanks!

TimMonko · 2026-01-06T21:14:22Z

@melissawm I'm not sure what's up with the Codespell fail because it should be skipped

docs/.codespellrc

Line 3 in ab4b01d

    
           skip = *.ai,*.css,*.ipynb,*.py,*.svg,.git*,./ruff_cache/,./.venv_*,gallery,.codespellrc,EULA.md,docs/release/index.md

and in the release index PR thats what I said it was for in the commit: 86d9c5f (#838)

Should it be ./docs/release/index.md? Not sure why it would have been working before though. Codepsell hasn't had a release for a year so its not like behavior should change

melissawm · 2026-01-06T21:28:52Z

Ohh I see. let me investigate

melissawm · 2026-01-06T21:42:20Z

Wooo you were right @TimMonko , thanks!! 🙏🏻

TimMonko · 2026-01-06T21:46:13Z

Maybe we just got really lucky for a few months that there wasn't a misspelled truncation in that file? LOL

TimMonko

Looks good to me! I think the remaining issues have been fixed!

psobolewskiPhD

let's go!

melissawm · 2026-01-10T21:06:06Z

Gentle ping! This may help @guiwitz continue with the Open Images page 😄

TimMonko · 2026-01-10T22:27:53Z

You can just merge next time @melissawm . There's two approvals already 🫣

melissawm · 2026-01-11T00:32:49Z

I hate self merging!! But it's noted 😁

# References and relevant issues Depends on napari/docs#881 # Description Updates link to Getting Started guide in Help menu. The other links in the Help menu did not change in that PR. --------- Co-authored-by: Grzegorz Bokota <bokota+github@gmail.com>

# References and relevant issues Follow-up to #881 # Description While reading through the new quickstart, I noticed this mention of an un-maintained plugin. For a while, the plugin did not work, but I do think it does appear to be fixed now MouseLand/cellpose-napari#51 (comment) I propose we remove this very small mention. We can consider adding back plugins once we have our review system in place. My preference would be for us to make a "starter plugins" guide, rather than a short quip (that's hard to notice because of its placement!) in this quick start. There already is good detail here pointing people towards the hub :)

github-actions bot assigned melissawm Oct 30, 2025

github-actions bot added the documentation Improvements or additions to documentation label Oct 30, 2025

melissawm added globias hackathon and removed documentation Improvements or additions to documentation labels Oct 30, 2025

melissawm force-pushed the usage-reorg branch from e4c5b99 to 1174f15 Compare November 22, 2025 12:47

github-actions bot added the documentation Improvements or additions to documentation label Nov 22, 2025

melissawm marked this pull request as ready for review November 22, 2025 12:52

melissawm mentioned this pull request Nov 29, 2025

Change link to getting started in Help menu napari/napari#8455

Merged

willingc approved these changes Nov 30, 2025

View reviewed changes

Czaki reviewed Dec 3, 2025

View reviewed changes

docs/tutorials/cell_tracking.md Outdated Show resolved Hide resolved

Czaki reviewed Dec 3, 2025

View reviewed changes

melissawm force-pushed the usage-reorg branch from 8d57535 to 139a628 Compare December 3, 2025 14:19

DragaDoncila added this to the 0.7.0 milestone Dec 11, 2025

melissawm force-pushed the usage-reorg branch from 9aba60b to 6e2ca27 Compare December 20, 2025 21:25

psobolewskiPhD reviewed Dec 22, 2025

View reviewed changes

docs/getting_started/quick_start.md Outdated Show resolved Hide resolved

melissawm and others added 10 commits January 6, 2026 17:30

Previous commit

75d4080

Address reviews

2de2641

Emphasize layers as data

e1e4bc2

Add release notes to fix CI failures

3f78d03

Improve quickstart, add plugins content

5b5df61

Update docs/getting_started/open_images.md

cd6f7b0

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>

Update docs/getting_started/quick_start.md

9a8b083

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>

Update docs/getting_started/open_images.md

f4e7d5b

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>

Fix grid/cards

cb0b5f5

Re-title card

c61f8d5

melissawm force-pushed the usage-reorg branch from 1af1f8b to c61f8d5 Compare January 6, 2026 20:30

melissawm requested a review from psobolewskiPhD January 6, 2026 20:31

Try to fix codespell failure

7ecab59

TimMonko approved these changes Jan 6, 2026

View reviewed changes

psobolewskiPhD approved these changes Jan 7, 2026

View reviewed changes

TimMonko added the ready to merge label Jan 7, 2026

Merge branch 'main' into usage-reorg

c8f5978

TimMonko merged commit 009a87c into napari:main Jan 10, 2026
8 checks passed

guiwitz mentioned this pull request Jan 13, 2026

Improve open image section #907

Open

TimMonko mentioned this pull request Jan 13, 2026

Remove mention of outdated plugin from quick start #908

Merged

Reorg of the Usage section of the docs #881

Reorg of the Usage section of the docs #881

Uh oh!

Conversation

melissawm commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

References and relevant issues

Description

Uh oh!

psobolewskiPhD commented Nov 25, 2025

Uh oh!

brisvag commented Nov 25, 2025

Uh oh!

DragaDoncila commented Nov 26, 2025

Uh oh!

melissawm commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

willingc commented Nov 29, 2025

Uh oh!

melissawm commented Nov 29, 2025

Uh oh!

willingc commented Nov 30, 2025

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

willingc commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Czaki left a comment

Choose a reason for hiding this comment

Uh oh!

melissawm commented Dec 3, 2025

Uh oh!

guiwitz commented Dec 5, 2025

Uh oh!

brisvag commented Dec 5, 2025

Uh oh!

melissawm commented Dec 5, 2025

Uh oh!

Czaki commented Dec 16, 2025

Uh oh!

melissawm commented Dec 20, 2025

Uh oh!

psobolewskiPhD Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

willingc Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

melissawm Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

melissawm commented Jan 6, 2026

Uh oh!

TimMonko commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

melissawm commented Jan 6, 2026

Uh oh!

melissawm commented Jan 6, 2026

Uh oh!

TimMonko commented Jan 6, 2026

Uh oh!

TimMonko left a comment

Choose a reason for hiding this comment

Uh oh!

psobolewskiPhD left a comment

Choose a reason for hiding this comment

Uh oh!

melissawm commented Jan 10, 2026

Uh oh!

TimMonko commented Jan 10, 2026

Uh oh!

Uh oh!

melissawm commented Jan 11, 2026

Uh oh!

melissawm commented Oct 30, 2025 •

edited

Loading

melissawm commented Nov 29, 2025 •

edited

Loading

willingc commented Nov 30, 2025 •

edited

Loading

TimMonko commented Jan 6, 2026 •

edited

Loading