From what I understood from the numerous discussions about Documentation and from the tour, Documentation
is based on the following hypothesis:
documentation based on examples is more useful than a documentation based on specs.
The problem I currently see with the Documentation
is that it assumes that this hypothesis is true.
My proposal is: don't assume this; let the community prove or refute this hypothesis by upvoting the most useful pieces and downvoting the least useful ones.
If your initial hypothesis is true, we expect that the most voted pieces have prioritised examples. If there are no examples in the most voted documentation, then your hypothesis was refuted.
My hypothesis is that examples-based documentation is not a universal: some topics require explaining a concept through words, others an example is sufficient and advantageous. However, I assume that this may be wrong, because I haven't tested it.
IMO, the problem is that Documentation
is currently presented in a way that it gives too much emphasis on writing examples, and it does not allow other possible hypothesis to be tested. More importantly, because you haven't presented any evidence that this is the best way to write documentation, only those that believe in this are willing to participate.
And guess what, there are lots of folks that are not convinced (me included) that this hypothesis is true.
Given the tools that Documentation
has, I believe they would do a much better job to all of us by being a great tool to test the hypothesis, than being a tool that assumes it to be true. One of the best pieces of evidence of this is that lots of folks are extremely annoyed about the goal and focus of the Documentation
. And believe me, we all want this project to succeed!
In summary, I suggest that we relax the example-focus of the Documentation
, and allow more freedom for the community to use the tools to figure out what is the best way to write documentation. This could start by downgrading the It's all about examples.
section of the tour.
If not, then present us undeniable evidence that documentation that prioritises examples is the most useful documentation.
If not, then don't expect folks to use their time on something that they don't believe in.
My hypothesis is that examples-based documentation is not a universal: some topics require explaining a concept through words
Yep, those already got books, tutorials, formal education, courses, and whatnot. This is exactly why we need a fluffless Documentation - without those topics. IMHO Documentation does not aim to be a complete reference of all what can be told. It aims to be more like a giant cheatsheet. That might be a better name for it, even.