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.
Do you have more examples for things missing here?
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 , inverted pyramid , 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.
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.
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 ;)
I can't count the number of times I've looked at the home page of documentation for some product and it has felt like stumbling into a teenagers' conversation conducted entirely incomprehensible references, slang and in-jokes.
An introduction needs to say what the thing is, what it does and why someone might want to use it. Usually that can be expressed in a few sentences.
I don't really see it as a mode of documentation in the way that the four components I describe are.
I wouldn't worry too much though. The framework isn't intended as a "do this, all this and nothing but this or you're doing it wrong" final statement on the art of documentation.
It's more a tool for thinking about what you are writing, for whom, and how you can best write it for them. It's to be used however someone finds it useful.
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".
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.
It looks like he was at least partly inspired by this article .
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.
 - https://scrawl-v8.rikweb.org.uk/
Daniele Procida built on this and formalized it through this resource, which is really amazing and definitely the best resource for writing docs that I know of.
Thanks for rewriting them!
Sadly, we can't do anything about the tens of thousands of existing Redux tutorials out there, and I keep seeing people post new Redux tutorials even now that don't make any mention of RTK at all. Kinda frustrating, but all I can do is keep trying to improve our docs, answer questions, and let people know that it's a lot easier to learn and use Redux today.
I don’t think I really ever have to look at the redux docs, which probably doesn’t help.
I definitely don't expect everyone with an existing Redux codebase to know that RTK exists already (although sure, I'd love to wave a magic wand and update every Redux codebase to RTK overnight). But it is sad to see new tutorials being posted that A) don't teach anything new compared to the plethora of existing tutorials, and B) continue to teach older patterns that are the same things people have complained about Redux over the years.
So, even though I'm spending a lot of time updating our docs and highlighting RTK as the default way to use Redux, many people just rely on whatever other courses and tutorials they've looked at for their knowledge.
One trick I learned many moons ago from a tech writer was what he called the "SEE" method - statement, example, explanation. I've never found any references to it. I've found it effective for simple cases such as helping engineer's "just get started"
to break writer's block. It's not a grand theory covering all doc types.
A similar (sub)concept: The Code Sandwich
Any demonstrative code block should be "sandwiched" between a sentence of introduction above and an explanation of what the code is doing below.
"Nearly everyone understands this. Nearly everyone knows that they need good documentation, and most people try to create good documentation. And most people fail."
In my experience, no, most people I've worked with couldn't care less. It's sad. Some people can't even be bothered to write good bug reports, features requests, or tasks...
I'd like the typical docs in Markdown or Asciidoc in flat files like a static CMS but within a page I'd like to have customer/choice dependent blocks.
So some free form text and then a block with instructions that are different per environment or customer or whatever. So based on a selection I'll only show the parts for Debian or Red Hat or whatever or I'll pull customer information out of a CMS system to show the customer only the parts relevant for her environment.
I know this exists but I can't find an example now. This is what I'd like to avoid: https://docs.nginx.com/nginx/admin-guide/installing-nginx/in... I don't want to show a Debian user all the stuff she's not interested in.
We'll have an offline, desktop version soon. http://miki.mimix.io
As food for thought, what changes would occur if documentation must be created first before any coding takes place? How about if produced in parallel? Too often, it is an artifact at the end.
I finally got management's attention when I stood up in one of our periodic group wide meetings and said "There is something that we do that is critical to our business but very inefficient because of the level of rework it triggers. Across a year we start this activity about once every two hours. What is it?"
The answer was of course 'create a document'. I'd used our document issuing system to find out how many docs our group had created in a year. As a group that conducted research tasks and process-heavy delivery projects for external customers, we did in fact create a lot of documents. We already had a document guidance framework, but it wasn't until management realised the overhead created by not following it that the necessary training and education in doc production finally got traction.
It's kind of like fitness -- you can do a million different things, but doing something is better than doing nothing at all. Just pick that something and go!
Are they ever used for anything besides pitching, i.e. after a project is completed?
This is much cleaner and not specific to a programming language. Gonna save this link for sure.
To complete the circle, https://divio.com is built in Gatsby (not the documentation though; that's in RST/Sphinx and published on readthedocs.com).
Do join if you're interested, even if it's just to hear Daniele's talk.
FastAPI's docs (recently front page on HN) are a great example of focused, concise documentation that knows exactly its purpose.
- xxx: One to two paragraph introduction
- About xxx: Generally explanation
- Using xxx: A bunch of how-to's
- xxx Reference: (id.)
The Tutorials quadrant is notably (and noticeably) absent and is what was then supplied by so many other places.
I have convinced my colleagues at work to use it as well: https://nimbus.guide/
1) Tutorials <- starting point
2) How To <- intermediate
3) Reference <- comes back to it regularly
4) Discussion <- final step to understanding
However as the video mentions, it's all connected in a circle, as perhaps having some discussion up-front(why, context, alternatives) is useful for newcomers to evaluate whether this project is worth diving into.
Curious as to whether the author(and everyone) thinks on how much "discussion" should be put into the "Getting Started" page.
Some of it is intuitive, but it's just great to have such a structured perspective.
Example topic is “Explicitness vs conciseness in naming” (it could be (over)simplified to “prefer explicit over concise naming”).
That's where you weigh up options, discuss alternatives, etc. If it's something you could read about in the bath or talk about over dinner, it goes there.
It doesn't matter which framework was used to write it.
Eh docs aren't that important; we've all used badly documented libraries before. Would better docs help? Sure, but let's not overstate their value.
The framework looks like a useful writing aid though.
With cost in mind, documentation quality brings the total cost up or down and can change the calculation entirely. It’s also implicitly taken into account when a team builds a POC and reports the time spent on it. Depending on if it took 3 weeks or 5 days, it will be a completely different perspective.
If no other library suffices, then customers will use yours. But they'll hate you. Over time, they might stop using your other contributions, even if they don't have any other choice.
In other words, would better/faster/more easily modified code help? Sure, but let's not overstate its value. We've all used badly designed code before. /s
Sure have, way too often. But if there's a choice, I'll pick the one with proper documentation every time (unless it's absolutely inferior of course).