Need for an "advanced topics" part?

[mih]

It occurred to me that we should decide whether or not we would consider a topic like "extending datalad" as in-scope scope for the book. It is clearly not "basic" and maybe not a use case. It would cover custom dataset procedures and writing one's own extension packages.

[adswa]

From my point of view, everything that is "stable" (i.e. API not planned to change) can be a part of the "basics" section. With this in mind, I think many extensions can fit into this part of the book, and would also be relevant and well-fitting to existing content, e.g. datalad containers. A "how to write an extension" part sounds super interesting to me personally, and we could include this as a fully hidden section (I believe this is possible with a "hidden" directive at the very start of the file) to not have people stumble upon it.
This currently makes sense to me as it would keep a potential extensions chapter and how to write own extensions close to each other. But I also think that this is equally possible to have something like an "advanced" part for experts and people that want to become experts that we could link to...

I believe this question will be easier to answer once content for these sections exist, I'll hopefully get to that in a bit of time.

[adswa]

Since we have http://handbook.datalad.org/en/latest/basics/101-144-intro_extensions.html now, I'd suggest to add content on how to create a custom extension right afterwards with no additional "advanced topics" part. The section http://handbook.datalad.org/en/latest/basics/101-124-procedures.html also has a findoutmore on how to write your own procedures.

[adswa]

I' revisiting this proposal as there are a few (upcoming) PRs that will go beyond basics of DataLad, namely

• the chapter on scaling up
• the chapter on DICOM to BIDS conversion
• the chapter on FAIR processing at scale with the UKBiobank project.

We could end the "Basics" at the current chapter 9 ("Help yourself"), and introduce an "Advanced" part of the book. The tentative content of this book part would be:

• Advanced options
• Extensions for Neuroimaging (working title)
• Go big or go home
• FAIR processing at scale (working title)
• tbc

This would make the Basics more managable: They'll appear shorter/less intimidating to a reader, they are almost complete content-wise (only metadata capabilities are missing, IMO). This book part could be marked as somewhat "stable", with little rearrangements or major changes (apart from maintenance) to be likely. Also, the Basics (and only the Basics) would be completely narrative-based. The more advanced chapters stray from the "Datalad-101 course" narrative.

[mih]

I like the idea of drawing a thicker line between basics and the rest.