Open adamltyson opened 10 months ago
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:
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.
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.
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 🤷
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!)
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.
Went with Specific applications
for now, but we can rename if we come up with something better.
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:
We currently have:
Proposed new structure
We could restructure the current tutorials, and add new ones to achieve the following:
Introductory tutorials
Application tutorials
57
Future work
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 https://github.com/brainglobe/brainglobe.github.io/issues/12