Improve tutorials/walkthroughs

[adamltyson]

Current status

Inspired by the Diataxis approach, and to facilitate teaching of BrainGlobe courses, it would be useful to improve the tutorials.

Diataxis distinguishes "How-to guides" and "Tutorials". We currently only have tutorials, and I think having both could be confusing for users. We could follow Diataxis, but have one section with:

• Introductory tutorials (i.e. Diataxis tutorials). These are easy to start with, require minimal set up and only aim to teach how a tool works. There will be no options for the user, the only aim is to understand something,
• Application tutorials (i.e. Diataxis how-tos). These will require more set up, and are likely to be based around some kind of neuroscientific technique/question. They will have some options (e.g. napari plugin/python API), and the idea is that users can apply them to their own data.

We currently have:

• 3D registration
• Probe segmentation
• Cell detection
• Bulk tracing analysis
• Atlas visualisation

Proposed new structure

We could restructure the current tutorials, and add new ones to achieve the following:

Introductory tutorials

• Atlas visualisation (keep as is)
• Register a brain to an atlas (a simplified version of 3D registration). Adaptation tracked in Simplify the 3D registration tutorial #82
• Manually segment basic features from a registered brain (tracked in Add a simple tutorial outlining brainreg-segment #83)
• Basic 3D cell detection on a small dataset using the napari plugin (Add basic cell detection tutorial #87)

Application tutorials

• Neuropixels probe segmentation (based on existing tutorial, but add some more analysis steps, it's currently a bit light). Tracked in Expand the neuropixels probe segmentation tutorial #84
• Bulk tracing analysis. This tutorial is pretty good, but could probably be improved. Standardise the bulk segmentation tutorial #85
• Whole brain cell detection and registration. This is ok, and very detailed, but it should be updated to brainglobe V1 at some point, making it clear it's combining multiple tools. Update the whole brain cell detection and registration tutorial to BG V1 #86
• Retraining the cell detection network. Lots of this is in the docs, so it might be possible to restructure existing material. Tutorial for retraining cellfinder #88
• application specific tutorial for brainrender napari #57

Future work

• bg-atlasapi
• bg-space
• brainrender tutorials (assuming the API is fixed)

Keen for feedback, particularly @alessandrofelder & @niksirbi. Essentially my plan is to move more information into (what we call) tutorials (nobody reads the docs) and make a clear split between (what Diataxis call) tutorials and how-to's.

Superceeds #12

[niksirbi]

I like the idea, but I find the naming of "Introductory" vs "Application" tutorials a bit confusing.
I would opt for naming the "Introductory" ones as "Quickstart" or "Getting Started". From your bullet points, they naturally split into distinct topics:

• Visualisation
• Registration
• Manual segmentation
• Cell detection

These 4 concepts can be introduced in these tutorials with small data examples, as you've outlined. They can be interlinked to "Explanations" that introduce the relevant terminology (e.g. "atlas", "reference", "label", "mask", etc.)

The "Application Tutorials", can stay as described above, but we should consider other names. Maybe "Specific applications" / "How-to guides"? But I don't feel strongly about any of these names, so could be a subjective thing.

[adamltyson]

I like "Getting started" and "Specific applications". I've added these to #90

I think we can't split the "Getting started" into those sections you outline, just because as BG grows, we will need more introductory tutorials in these sections. In general, most users aren't users of "BrainGlobe", but specific parts.

[alessandrofelder]

I like the way you suggest to split up. Minor question mark around the word "Application" - I assume here it's in the sense of applying BrainGlobe tools to a specific real-world(-ish) situation (but it technically could be ambiguous and mean "software application" in the context, and therefore be confusing). Can't think of a better term right now though, and it's good enough so 🤷

[alessandrofelder]

maybe "Advanced tutorials" instead of "specific applications" as we assume these users have basic familiarity (ie be experienced enough to sow a real wound in the Diataxis doctor-and-suture example of the difference between tutorial and how-to)? But I'm not fussy (in this case!)

[adamltyson]

I don't really like advanced tutorials, as it suggests that they may be harder in some way. The distinction I'm trying to go for is the diataxis tutorial/how-to distinction, but I think that's very unclear for users.

[adamltyson]

Went with Specific applications for now, but we can rename if we come up with something better.