napari for beginners page

[chili-chiu]

📚 Documentation

Goal: Create a page for people to know what napari does and have the first try efficiently.

Target audience:

• Know nothing about napari
• May or may not know Python
• Interested in image visualization and/or analysis

Possible contents:

• [ ] 3 minutes "napari overview" video
• [ ] Bullet point of main features
• [ ] Quick start tutorial : installation (viewer + plugins), open sample image, visualization, analysis, export
• [ ] "Next steps" with hyperlinks to other materials

Dependencies:

• [ ] bundled app?

@melissawm @DragaDoncila @GenevieveBuckley @neuromusic @dgmccart @tdimino @liaprins-czi

[DragaDoncila]

Thanks for starting this conversation @chili-chiu.

May or may not know Python

I actually think here we should assume they don't know Python i.e. they have run or written a few small notebooks, but are unfamiliar with programming/development practices, using the terminal, packaging, the GitHub workflow (e.g. opening issues or PRs).

installation (viewer + plugins)

I think we should spend a lot of time here making a detailed installation tutorial for the package - as the bundled app is still unstable and doesn't provide the full functionality offered by the package. This tutorial should include:

• detailed instructions for installing anaconda and a brief explanation on what it is and how to use it
• instructions for creating an anaconda environment (for both Windows & Mac), activating it, checking it's active, deleting it and making a new one
• instructions for launching a notebook and launching napari from within the notebook (?)

I also think we should have a "Quick debug" guide for starting napari. New users might run into easily fixable issues but give up if there's nowhere for them to go. The issues I'm thinking of would be:

• they're trying to run napari without having activated the environment
• didn't use "napari[all]" and they don't have a qt backend
• confusion between running from script, from command line or through ipython
• ~the known issues with installing on BigSur - @tlambert03 do you know if this is still a thing?~ - not still a thing
• checking that anaconda is using the env Python not bin Python and how to fix it
• others? ...

Another resource I think we should have (in general but in particular for new non-python users) is a quick tutorial on querying/changing information on layers, dims, camera and the viewer itself from the built in ipython console.

That's all I can think of at the moment!

[tlambert03]

the known issues with installing on BigSur - @tlambert03 do you know if this is still a thing?

nope the standard install method works fine on big sur now

[dgmccart]

May or may not known python

I think for this page to be most effective we should assume they are completely new to image visualization and analysis. Capturing the folks that need the most hand-holding will be challenging, but I think doing this from the start will save work in the future.

[neuromusic]

I think its important here to be a bit more specific with the goal of this page.

I'd argue that the primary goal here should be "Create a page for people to know what napari does" and the secondary goal is "have the first try efficiently."...

The first goal is relevant to a very broad audience (Python and non-Python alike), then they will decide whether or not to pursue the second.

For all of the reasons that @DragaDoncila noted, there's a large barrier to entry re: Python that's necessary for installing and managing napari, but that will get better as the bundled app improves. I don't personally think its worth bending over backward trying to acquire these users until the bundled app is ready for them.

For these reasons, I propose that this page should be limited in scope to "in-viewer" functionality, starting with an already-installed napari and closing with "Ready to get started? Click here to learn how to install napari", which can then link to whatever the latest installation guide is for the bundled app or the library.

[DragaDoncila]

I don't personally think its worth bending over backward trying to acquire these users until the bundled app is ready for them.

I'm not sure that I agree with this. I do think that in the longer term the bundled app will be the "solution" for inexperienced users. However, even if the bundled app gains feature parity with the package, I think interacting with napari programmatically will still remain a huge benefit of the application.

We've often talked about napari being a "gateway to Python" or more specifically "a gateway to image analysis in Python". If this is a goal (and I think it absolutely should be), then we need to provide the tools for that to happen, rather than just hoping users will find their way around. I think a detailed installation guide and a "napari API overview" are fundamental tools we should provide to open that gateway.

Additionally, napari is currently growing very rapidly. The pace of its user base growth may soon (if it isn't already) outpace our development on the bundled app. While we catch up, I think these documents can be useful for onboarding new users (and developers!), supporting inexperienced users and fostering a feeling of community support - we're not saying "napari's not quite ready, come back later". Instead we're saying "napari's not quite ready, but we're here for you until it is".

For these reasons, I propose that this page should be limited in scope

I do wholeheartedly agree with this - we want to make sure we're completely aligned on what we want this document to contain before we start writing. We may end up with plans for multiple documents out of this discussion, but I'd prefer that to this document being a hodge podge of assorted information without a clear narrative.

[chili-chiu]

Napari's access to Python is certainly a feature worth highlighting, and we can explicitly showcase it as a "feature" not a "requirement".

We can: (1) Show it in the short video, along with other GUI interactions (2) List it under bullet point of main features

As for installation and in general, perhaps only offer the most straightforward method (even if it only works 80% of the time) and avoid debugging etc. in the same page, instead we can use hyperlink to other page with more detailed installation guide. This could make the first impression of napari less intimidating :)

I would imagine this is going to be a relatively short page, but with many hyperlinks.

[psobolewskiPhD]

I will say from experience: a sufficiently captivated user will put up with a lot of difficulties in installation—if they see the rainbow. The speed, versatility, and extensibility of napari (thanks to the python eco-system) are the rainbow. 🌈 (Warning: the rainbow can be addictive!)

Also, for me, the layer model of napari really clicked. To me, it's much more intuitive—and convenient—than multiple windows, etc. This was a major selling point of napari for me, a long time ImageJ user—I'm dating myself, but I started when it was still NIH Image. So showcasing the power of layers (and opacity/blending, etc.) would be a major point of emphasis, along with the "click and it's 3D 🤯 " feature.

[neuromusic]

I think a detailed installation guide and a "napari API overview" are fundamental tools we should provide to open that gateway.

Oh agreed there @DragaDoncila !! By "bending over backward" I was more referring to exhaustive documentation on all of the pitfalls of getting things like Python environments and paths working properly. We should absolutely include a clear, concise opinionated guide to getting napari installed on a clean system.

[chili-chiu]

Here's the very first attempt: https://github.com/chili-chiu/napari-tutorial/blob/main/napari%20quick%20start.ipynb

• Not putting it as PR because of some embedded images/gifs, waiting for doc reorg to see how to handle those the best.
• What about changing the title from "napari for beginner" - which focuses on who - to "napari quick start" - which focuses on the task? any preference?
• Python is upfront but with lots of links to plugins