Structure of individual tutorials

[liaprins-czi]

Tutorials employ "a simple example" convention to explain basic principles like layers, which should accelerate performance, but don't provide sufficient agnosticism from example to convey ability to perform action outside of the given example (ie not on the photographer picture but my own).

Block paragraph text make it difficult to follow what should be an instructional guide.

Preliminary paragraphs reference "assumptions" about what user has already done until now, which are valuable but slow down comprehension and should be placed elsewhere.

Reading the Viewer Tutorial, it starts off by saying:
"The viewer is organized into a few key areas:
main canvas
layer list
layer controls
new layer buttons
viewer buttons
console
dimension sliders
status bar
We’ll go through each of these in the next sections."
However, it doesn't have a section for "console". Also, the content doesn't follow the order in the list exactly (Viewer Buttons are out of order). Furthermore, the heading style isn't consistent for all of them (most are a smaller sized font, except for Dimension Sliders).

---

Recommendation

Consider user knowledge, if value is to show example or explain process (these are different things).
Demonstrate reproducibility on own image.

Reorganize in more directed, bulleted fashion to allow digestible reading and following along while performing actions.

In the Viewer Tutorial specifically:

• Explain about the console. If it has enough info and is distinct enough from the other UI elements (it may be) it may deserve its own tutorial page. In that case I'd recommend still using this "Viewer Tutorial" page to explain briefly where in the UI the console appears and what it can be used for. Then include link to the console-specific tutorial (if decide to give it its own page).
• Use consistent heading sizes (the smaller size for each element, since they are sub-hierarchical to the overarching "layout of the viewer" section).
• Keep the content sections in the order in the top list.
• Top list could act as anchor links jumping to each section below.

Moderate issue
◆◆◆ High content writing work
●●○ Medium design work
▼▽▽ Low development work

[psobolewskiPhD]

The viewer tutorial has undergone a significant update:
napari/docs#65
That said, the console docs could probably still be improved, perhaps in a dedicated page.