Build your own DataLad adventure

[adswa]

Treat this issue as [WIP] - I'm essentially just taking notes to disentangle my brain.

Following up with a suggestion by @loj in #8, I'm brainstorming potential "DataLad adventures" we can let readers "choose" from. If we can find a way to make these "adventures" work, those will be the "Basics" section of the handbook (between introductory sections and use cases). Following up on an idea of a "general example dataset" we could keep whatever example dataset we come up with the theme of each adventure (but we somehow may want to keep in mind that it should not be a read-from-start-to-end book). I believe the general idea behind this is to not mimic a "documentation" structure in which we describe every command sequentially and in detail, but rather identify common, generic workflows. (But I'm not sure whether I am conflating "the basics" meant as building blocks for such an adventure too much with use cases here. plus I'm currently doubting whether this is the modular structure we are also aiming for...) One potential problem I'm seeing while writing this is that we have a lot of duplication about commands between the different "adventures". Also, while simple now with only stable commands, this might become a mess the more complex commands get included. However, it might be more helpful to see commands joined together in different workflows instead of having them stand next to each other unconnected but without duplication.

The tool to visualize this (general idea, not necessarily what I'm sketching out here) likely is this: http://blockdiag.com/en/index.html.

• A1 "I'm a new player (no experience in the terminal) and need the pre-game tutorial"
  • Chapter 0: General prerequisites
• A2 "I want to version control a new project (local only)"
  • Chapter 1: Local workflows (Section 1: Starting a new dataset)
    • could include: create, status, diff, save
• A3 "I want to start version controlling an existing project (local only)"
  • Chapter 1: Local workflows (Section 2: Existing projects)
    • could include: install + create, status, diff, save
• A4 "I want to start a collaborative project with DataLad"
  • Chapter 2: Shared workflows
    • could include: Read A1, + publish (+ update?)
• A5 "I want to use DataLad in an existing collaborative project"
  • Chapter 2: Read A2, + publish (+ update?)
• A??
  • Chapter XY
    • • run
• A?? "I want to share data"
  • Chapter XY: ??
• A42 "I ran into troubles. How can I help myself?"
  • Chapter XY: When things go wrong
• A0 "I need a quick reference about the commands covered in this book!"
  • maybe a "quicklinks" chapter, with all commands, a 1-2 sentence description what they can do, and links to the chapters they are covered in. This can be the most "documentation-like" section and will be helpful for navigation and overview for people who might just want to re-read things.

I will continue developing my messy thoughts on this tomorrow.

[adswa]

I'm closing this (for now). Currently, the developments in #25 outline a narrative-based, continuous structure, and we will try to make this work throughout the book. This sacrifices the "modular approach from the start", but we plan on grouping content in a modular fashion as best as we can once it exists, thus removing the difficulty to plan/structure everything beforehand.