I like the idea of this (and have been lucky enough to meet the creator a couple of times at PyconUK - he's a talented and very friendly chap), but I have a reservation about being this rigid about differentiating between the various areas of documentation in this way.
During a sprint I was told that the docs I was preparing (not by Daniele, for the record) were mixing modalities and not acceptable because of this. Not pulling rank, but I've been a teacher for 20+ years, and I have a reasonable ida of how to explain things and how to scaffold learning so that people can both get things done and progress with understanding happening as part of that.
As long as there's not total rigidity then this is a great tool for deciding how to produce documentation and what each type of document should do. I often see examples in documentation (numpy springs to mind) where the examples could be a lot better chosen rather than 'magic from the sky'. A good, well chosen example can provide a lot of learning while illustrating usage, a corner case or other things to be aware of.
During a sprint I was told that the docs I was preparing (not by Daniele, for the record) were mixing modalities and not acceptable because of this. Not pulling rank, but I've been a teacher for 20+ years, and I have a reasonable ida of how to explain things and how to scaffold learning so that people can both get things done and progress with understanding happening as part of that.
As long as there's not total rigidity then this is a great tool for deciding how to produce documentation and what each type of document should do. I often see examples in documentation (numpy springs to mind) where the examples could be a lot better chosen rather than 'magic from the sky'. A good, well chosen example can provide a lot of learning while illustrating usage, a corner case or other things to be aware of.