9 ms·

I review a lot of technical software documentation. This is one of my go-to resources for explaining how docs should be organized. These ideas are generally acc

I review a lot of technical software documentation. This is one of my go-to resources for explaining how docs should be organized. These ideas are generally accepted among software technical writers; you may just hear them use slightly different words for each doc type. E.g. I use "overview" instead of "explanation". I'll also mention that this framework isn't comprehensive; there are other types of critical documents that aren't explained here, such as release notes. I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc. Edit: I suppose you could argue that release notes fall under the category of reference-oriented, but when I look at the guidelines for reference docs it's clear that the Divio people were thinking about API references.

k__ 6y ago
"this framework isn't comprehensive; there are other types of critical documents that aren't explained" Do you have more examples for things missing here?
- hyperion2010 6y ago
  Implementation experience reports come to mind.
- kaycebasques 6y ago
  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".
- twinprime 6y ago
  Also curious myself..
- hollasch 6y ago
  Speaking for myself, two items I often find missing: the overall summary and the rationale. Many times I've gone to a set of documentation wondering what exactly the thing _is_. Let's take the JavaScript language, for example. The very first thing that should be documented is a short description of what exactly JavaScript _is_. This could be a single sentence, should probably be at least a paragraph, and should be no more than a page. It boggles my mind how often this critical piece of information is omitted entirely. The rationale quickly orients the reader to the landscape of similar solutions. It's very rare that something has no peer of any kind, and it's quite useful to understand why this particular thing exists, and how it can be distinguished from other similar solutions. The Python language, for example, has a number of attributes that separate it from other computer languages. This can be concrete (it comes with constraints that lend themselves to readable programs), or they can be aspirational (Python aspires to be an easy language to pick up, particularly for non developers). This can go deep, and rapidly descends into matter that my be quite useful and interesting, but belongs in an appendix or other separate matter.
- hmsimha 6y ago
  FAQs and code comments don't really fall cleanly into any of these categories.
- muench 6y ago
  Greg Wilson writes about a useful tool for thinking about types of documentation [0] incorporating the novice-competent practitioner-expert framework. It looks like he was at least partly inspired by this article [1]. [0] https://third-bit.com/2019/08/08/documentation-types/ https://third-bit.com/2019/08/08/documentation-types/ [1] https://third-bit.com/2018/10/18/four-forms-of-docs/ https://third-bit.com/2018/10/18/four-forms-of-docs/
rikroots 6y ago
I used this resource as inspiration for when I had to rewrite the documentation for my JS library[1]. There's still a lot of work involved - particularly when it comes to finding the enthusiasm to write up another tutorial lesson or 'How Do I?' note but - overall - the documentation I have now is a lot easier to maintain and update as the library evolves. How useful it is for others ... I don't know the answer to that one. But knowing the documentation satisfies my needs (it's a Big Library; I'm constantly forgetting small details about how to use it) is enough for me. [1] - https://scrawl-v8.rikweb.org.uk/ https://scrawl-v8.rikweb.org.uk/

k__ 6y ago

"this framework isn't comprehensive; there are other types of critical documents that aren't explained" Do you have more examples for things missing here?

hyperion2010 6y ago
Implementation experience reports come to mind.
kaycebasques 6y ago
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".
twinprime 6y ago
Also curious myself..
hollasch 6y ago
Speaking for myself, two items I often find missing: the overall summary and the rationale. Many times I've gone to a set of documentation wondering what exactly the thing _is_. Let's take the JavaScript language, for example. The very first thing that should be documented is a short description of what exactly JavaScript _is_. This could be a single sentence, should probably be at least a paragraph, and should be no more than a page. It boggles my mind how often this critical piece of information is omitted entirely. The rationale quickly orients the reader to the landscape of similar solutions. It's very rare that something has no peer of any kind, and it's quite useful to understand why this particular thing exists, and how it can be distinguished from other similar solutions. The Python language, for example, has a number of attributes that separate it from other computer languages. This can be concrete (it comes with constraints that lend themselves to readable programs), or they can be aspirational (Python aspires to be an easy language to pick up, particularly for non developers). This can go deep, and rapidly descends into matter that my be quite useful and interesting, but belongs in an appendix or other separate matter.
hmsimha 6y ago
FAQs and code comments don't really fall cleanly into any of these categories.
muench 6y ago
Greg Wilson writes about a useful tool for thinking about types of documentation [0] incorporating the novice-competent practitioner-expert framework. It looks like he was at least partly inspired by this article [1]. [0] https://third-bit.com/2019/08/08/documentation-types/ https://third-bit.com/2019/08/08/documentation-types/ [1] https://third-bit.com/2018/10/18/four-forms-of-docs/ https://third-bit.com/2018/10/18/four-forms-of-docs/

rikroots 6y ago

I used this resource as inspiration for when I had to rewrite the documentation for my JS library[1]. There's still a lot of work involved - particularly when it comes to finding the enthusiasm to write up another tutorial lesson or 'How Do I?' note but - overall - the documentation I have now is a lot easier to maintain and update as the library evolves. How useful it is for others ... I don't know the answer to that one. But knowing the documentation satisfies my needs (it's a Big Library; I'm constantly forgetting small details about how to use it) is enough for me. [1] - https://scrawl-v8.rikweb.org.uk/ https://scrawl-v8.rikweb.org.uk/