3 ms·

Introductions. The Divio site itself starts with an introduction yet it's not listed as one of the content types! You could argue that introductions fall into t

Introductions. The Divio site itself starts with an introduction yet it's not listed as one of the content types! You could argue that introductions fall into the understanding-oriented category but when I read the guidelines about explanations it's not particularly clear how to write a good introduction, and the goal feels somewhat different. I think the principles of information foraging [1] are probably most helpful towards understanding how to create a good introduction. Announcements (similar to release notes but focused on a single topic). We do these a lot on web.dev. Journalistic principles can help a lot towards creating useful announcements: answer the 5 Ws [2], inverted pyramid [3], etc. Case studies. In this case the goal is to persuade the reader to make a change and to do that you need to focus on what's in it for them. The journalistic principles mentioned earlier are also very helpful here. Code samples. How do you organize a big collection of code samples for easy discoverability? Some projects make small code samples in the spirit of how-to guides (i.e. the code samples only show how to do one particular task), other people do them more in the spirit of tutorials (i.e. it shows you a working end-to-end realistic application). The best approach is probably to do both. Again I think the Divio framework can help guide these decisions, but looking at the Divio framework narrowly, there's nothing explicitly focused on code samples. One might argue that code samples aren't documentation, but in my experience a single good code sample sometimes gets the job done much better than any of content types that Divio mentions. [1] https://en.wikipedia.org/wiki/Information_foraging https://en.wikipedia.org/wiki/Information_foraging [2] https://en.wikipedia.org/wiki/Five_Ws https://en.wikipedia.org/wiki/Five_Ws [3] https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism) https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)

dvaun 6y ago
Thank you for your summary of these items and for providing references.
ericholscher 6y ago
You should submit a talk to one of our Write the Docs conferences (https://www.writethedocs.org/ https://www.writethedocs.org/) -- this is a great start to a talk abstract :)
- bocklund 6y ago
  Daniele Procida already has a great Write the Docs talk on this subject already. It is indeed a fantastic talk. https://youtu.be/qK-AnF5FJTs https://youtu.be/qK-AnF5FJTs
DanieleProcida 6y ago
Thanks for the kind words! You are quite right, there are various things that aren't included in the scheme, that ought to be included in a complete set of documentation. Other examples could be: release notes (though you could include them in reference), contribution guide (though it could be part of how-to) and of course, the Introduction you mention. Mostly I think that these things probably belong outside the scheme, in the same way that say an appendix or an introduction falls outside main body of text in a book. An introduction (in documentation) is basically marketing: a reason for someone to keep reading. For me the scheme is not so much a complete list of every kind of thing that must be written (I think it goes without saying that you need to create useful contents tables for example) as a guide to how I should be writing and a reminder why I am writing.
- bigiain 6y ago
  > Mostly I think that these things probably belong outside the scheme Yeah, I think somethings count as "meta documentation" and are "documentation about the documentation" instead of the actual documentation. "contribution guides" to me are definitely that, "introductions" are mostly that. I reckon licenses are probably "meta documentation" too (since they'll also be in the source code). "release notes" are a bit of a grey area in my head (I'd consider at least major version update release notes and any depreciation/removal of features to be "part of the doco".
- janekm 6y ago
  I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation. An introduction to both the system goals and overall architecture provide essential context for the rest of the documentation, and can even provide the scaffold to structure it around. It is all too common for writers of documentation (deeply embedded in the project) to forget that the person reading the documentation may have no clue what the whole system is trying to achieve (especially so in public-facing documentation... how many times do you see a link on HN to a documentation page with no explanation of what "a BUZZY GRAPHEME WRANGLER" actually is?). Also... by your analogy, I am fairly certain that a guide to writing a technical book would dedicate a fairly considerable amount of space to the topic of a good introduction ;)

dvaun 6y ago

Thank you for your summary of these items and for providing references.

ericholscher 6y ago

You should submit a talk to one of our Write the Docs conferences (https://www.writethedocs.org/ https://www.writethedocs.org/) -- this is a great start to a talk abstract :)

bocklund 6y ago
Daniele Procida already has a great Write the Docs talk on this subject already. It is indeed a fantastic talk. https://youtu.be/qK-AnF5FJTs https://youtu.be/qK-AnF5FJTs

DanieleProcida 6y ago

Thanks for the kind words! You are quite right, there are various things that aren't included in the scheme, that ought to be included in a complete set of documentation. Other examples could be: release notes (though you could include them in reference), contribution guide (though it could be part of how-to) and of course, the Introduction you mention. Mostly I think that these things probably belong outside the scheme, in the same way that say an appendix or an introduction falls outside main body of text in a book. An introduction (in documentation) is basically marketing: a reason for someone to keep reading. For me the scheme is not so much a complete list of every kind of thing that must be written (I think it goes without saying that you need to create useful contents tables for example) as a guide to how I should be writing and a reminder why I am writing.

bigiain 6y ago
> Mostly I think that these things probably belong outside the scheme Yeah, I think somethings count as "meta documentation" and are "documentation about the documentation" instead of the actual documentation. "contribution guides" to me are definitely that, "introductions" are mostly that. I reckon licenses are probably "meta documentation" too (since they'll also be in the source code). "release notes" are a bit of a grey area in my head (I'd consider at least major version update release notes and any depreciation/removal of features to be "part of the doco".
janekm 6y ago
I honestly also think it is worth mentioning introductions as an essential part. I somewhat disagree that it is outside the scope of a scheme of documentation. An introduction to both the system goals and overall architecture provide essential context for the rest of the documentation, and can even provide the scaffold to structure it around. It is all too common for writers of documentation (deeply embedded in the project) to forget that the person reading the documentation may have no clue what the whole system is trying to achieve (especially so in public-facing documentation... how many times do you see a link on HN to a documentation page with no explanation of what "a BUZZY GRAPHEME WRANGLER" actually is?). Also... by your analogy, I am fairly certain that a guide to writing a technical book would dedicate a fairly considerable amount of space to the topic of a good introduction ;)