add draft brainrender-napari tutorial

[alessandrofelder]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
brainrender-napari is nearing an initial release, but we have no users docs.

What does this PR do?
Add a basic tutorial for how to interact with the BG atlas api via napari.

References

Closes #54
Partially addresses brainglobe/brainrender-napari#52

How has this PR been tested?

Downloaded artefact of website looks reasonable to me.

Is this a breaking change?

no

Does this PR require an update to the documentation?

no

Checklist:

• [n/a] The code has been tested locally
• [n/a] Tests have been added to cover all new functionality (unit & integration)
• [n/a] The documentation has been updated to reflect any changes
• [n/a] The code has been formatted with pre-commit

[alessandrofelder]

I've tried to follow the advice from diataxis.fr on tutorials for this

[adamltyson]

I've added some very nitpicky suggestions. I also think my suggestion for the admonition box broke the sequential numbering. Does putting everything as 1. automatically create the numbering? I've never seen this.

Generally it would be cool to add three things:

• Some images showing the buttons to click, and what a successful outcome is.
• Some more details as to why. Things like "the default reference image is X, if you want to view the other reference image Y, do this..."
• A (short) docs page alongside the other tools, so we can continue the pattern of comprehensive docs, and a specific application tutorial.

[alessandrofelder]

• Some more details as to why. Things like "the default reference image is X, if you want to view the other reference image Y, do this..."

While I'm happy not to be too dogmatic about it, I would argue that this goes against what the diataxis framework suggests for tutorials

It can seem problematic that we are asking a user to do things, without much explanation why. In practice, for the learner, it rarely is. The learner is focused on following your directions and getting a result; their time for wanting to know more about the why of what they’re doing will come later.

[alessandrofelder]

A (short) docs page alongside the other tools, so we can continue the pattern of comprehensive docs, and a specific application tutorial.

Yes, good call - separate tickets opened (#56, #57)

[alessandrofelder]

Does putting everything as 1. automatically create the numbering? I've never seen this.

Yes (makes it easier to insert a step without having to re-enumerate all subsequent ones)

[adamltyson]

• Some more details as to why. Things like "the default reference image is X, if you want to view the other reference image Y, do this..."

While I'm happy not to be too dogmatic about it, I would argue that this goes against what the diataxis framework suggests for tutorials

It can seem problematic that we are asking a user to do things, without much explanation why. In practice, for the learner, it rarely is. The learner is focused on following your directions and getting a result; their time for wanting to know more about the why of what they’re doing will come later.

Is this contrary to the diataxis framework? I'm not arguing we give them technical details that they don't need to carry out a task, I'm arguing that we should let them know what they're doing. If they aren't a zebrafish biologist, would they learn how to click a button, but not what the button does?

[alessandrofelder]

I'm arguing that we should let them know what they're doing.

Yes, I (and diataxis) would agree with this, I think. From my understanding, diataxis suggests for tutorials to give the learner as little room as possible to make their own decisions - they should be able to follow steps and they don't care (at first) why they are doing them, as long as they can achieve an example task. I've added some minimal explanations to the text now - more feedback welcome!

[alessandrofelder]

Thanks a lot for the thorough review, @adamltyson - maybe have another look as I've changed quite a bit?

[adamltyson]

Very nice. I left some v small stylistic suggestions.