When I come across bad documentation (which is often), by far the most common problem I find is that the information I needed just plain isn't present.
Articles like this one really aren't helping. If you wrote a piece of software I'm using that doesn't make you my teacher. It makes you someone offering a contract, and what I need to know is what that contract says.
The first duty of your documentation is to be complete and correct. Unless you've got that sorted, no amount of "putting yourself in the student's place" is going to give adequate results.
The docs are there. The information is there, but finding it, is so difficult, that I have often just said "bugger this for a lark," and written my own implementation.
There's two types of docs: The teaching kind, as the article mentions, and the reference kind, for helping folks that already have a start, to find what they need.
I generally do the second. It can be fairly easily generated from inline headerdoc comments, these days, but we still have the issue of indexing, and I still have my work cut out for me, there.
I actually like re-writing documentation, but if I can not reorganize the documentation too I am discouraged from re-writing. I believe a lot of contextual information is lost when people use confluence as a dumping ground and don't plan the structure of the documents.
I've emotionally moved to git for documentation, but I can not get people to follow or transition to better documentation methods once someone is emotionally tied to tribal knowledge and communication.
I agree that this article isn't doing something for me.
It barely covers the important points of what _should_ be done, and spends a lot of time lampooning bad approaches to documentation.
I also found the metaphor of "the black triangle" obscured the main point of that part of the argument, which to me was "have some foolproof basic starter setup to get a user up and running quickly".
The article is quite a bit smarter (if a bit long) than this comment. "The first duty of your documentation is to be complete and correct". The source code satisfies this demand. It is complete and it truly describes the product in all its details. But now we are stuck in 'act 1' of the article. So maybe we need some more helpful hints. O wait, there is an article called 'Teach, Don't Tell' that provides these helpful hints.
I have the opposite opinion. Most often, I'm looking for documentation that gets to the point. Just give me a straight answer so I can minimize time I spend reading docs and maximize time I spend using the thing. Tutorials tend to be annoying to read because there's a lot of information unrelated to the topic (setup, advice for beginner programmers) and important information that is missing because the tutorial inevitably chooses one use case and ignores the others.
If I had to pick, I'd rather a dev tell instead of teach. Other people will inevitably write their "how to do x in y" medium articles anyway. These days you can even get an LLM to write it for you, if there's docs that "tell".
I have a colleague who prioritizes maintaining control over teaching others. He tries to force a particular perspective, emphasizing the importance of his role while fostering dependency rather than sharing knowledge. This seems driven by a fear of losing his job.
My primary focus is backend development, where I assist developers and solve infrastructure challenges. However, I’m so effective in this role that I often end up boxed into it. I’ve been making an effort to expand into frontend development to broaden my expertise, but this colleague operates in that space and isn't the only one who has made it difficult for others to gain traction.
I agree with another commenter that this doesn't tell the entire story, but it tells almost all of it. Nowadays, I discover some new piece of software, visit the Documentation section of its website, and the first thing I see is `How to build SuperMung on the Whizzbang 47 using Mark Williams C'. I have no idea what SuperMung is for, how to use it, what errors I might make, and how to install it on Debian. Similarly, I go to the website for a new programming language, see some examples that give me little insight into what it is for, and find not even an incomplete language specification.
Proper documentation leads me by the hand, starting on what the software is for, what platforms it runs on, some examples of its use (including examples that show how it is useful for solving real-life problems), a thorough tutorial on how to use it, and finally a complete and properly indexed/searchable reference.
Back in the 1980s, I got myself in trouble: I promised a 100-page manual for a software system I had written, and I decided to do it in the then-new TeX. But this was before The TeXBook was published. So I learned TeX by reading the literate source for the code. The manual was duly ready on time, and served the literally thousands of students who relied on it for the next few years.
But when I finally got a copy of The TeXBook, I was astonished by how little I had actually known about using TeX. I had presumably been mostly using it to answer questions such as “why doesn't this work?”, and a lot of the overall principles had simply not been apparent to me. Once I had learned TeX properly, I learned a great deal about how it all worked by going back and reading the literate source. Knuth is a brilliant (if highly idiosyncratic) programmer.
My point here is to emphasize that when someone releases software, their job is not done unless people can learn to use it. That doesn't just mean completeness and accuracy, but a through-line, apparent to the reader, from learning what it does all the way to mastering it, along with the kind of reference information needed when using it.
This article is primarily about making documentation more effective for learning, not about replacing technical completeness. The best approach combines both perspectives rather than treating them as an either/or proposition.
Signals And Threads (a Jane Street podcast) had an interesting discussion about documentation [0]. There was also an interesting reference to literate documentation (I think similar to Jupyter notebooks but as documentation).
Good docs are rare like unicorns with a glowing horn.
It doesn't seem to move the needle like a shipped feature does, requires guessing other peoples' perspectives, involves devoted time and effort (that could, you know, be spent on actually useful things) and the effects of not doing it are invisible (but real: user rage, frustration and wasted time).
Only when the importance of good docs is understood will any effort be invested into it. It should be important if the goal is to have more people using something.
When I come across bad documentation (which is often), by far the most common problem I find is that the information I needed just plain isn't present.
Articles like this one really aren't helping. If you wrote a piece of software I'm using that doesn't make you my teacher. It makes you someone offering a contract, and what I need to know is what that contract says.
The first duty of your documentation is to be complete and correct. Unless you've got that sorted, no amount of "putting yourself in the student's place" is going to give adequate results.
There are 3 types of documentation:
1. Why/what 2. API spec 3. Tutorial
You need all 3. They are distinct, use different styles, and exist for different purposes and audiences.
My biggest peeve, is bad indexing.
The docs are there. The information is there, but finding it, is so difficult, that I have often just said "bugger this for a lark," and written my own implementation.
There's two types of docs: The teaching kind, as the article mentions, and the reference kind, for helping folks that already have a start, to find what they need.
I generally do the second. It can be fairly easily generated from inline headerdoc comments, these days, but we still have the issue of indexing, and I still have my work cut out for me, there.
Here's some stuff I wrote about my approach to documentation: https://littlegreenviper.com/leaving-a-legacy/
I actually like re-writing documentation, but if I can not reorganize the documentation too I am discouraged from re-writing. I believe a lot of contextual information is lost when people use confluence as a dumping ground and don't plan the structure of the documents.
I've emotionally moved to git for documentation, but I can not get people to follow or transition to better documentation methods once someone is emotionally tied to tribal knowledge and communication.
I agree that this article isn't doing something for me.
It barely covers the important points of what _should_ be done, and spends a lot of time lampooning bad approaches to documentation.
I also found the metaphor of "the black triangle" obscured the main point of that part of the argument, which to me was "have some foolproof basic starter setup to get a user up and running quickly".
The article is quite a bit smarter (if a bit long) than this comment. "The first duty of your documentation is to be complete and correct". The source code satisfies this demand. It is complete and it truly describes the product in all its details. But now we are stuck in 'act 1' of the article. So maybe we need some more helpful hints. O wait, there is an article called 'Teach, Don't Tell' that provides these helpful hints.
I have the opposite opinion. Most often, I'm looking for documentation that gets to the point. Just give me a straight answer so I can minimize time I spend reading docs and maximize time I spend using the thing. Tutorials tend to be annoying to read because there's a lot of information unrelated to the topic (setup, advice for beginner programmers) and important information that is missing because the tutorial inevitably chooses one use case and ignores the others.
If I had to pick, I'd rather a dev tell instead of teach. Other people will inevitably write their "how to do x in y" medium articles anyway. These days you can even get an LLM to write it for you, if there's docs that "tell".
I have a colleague who prioritizes maintaining control over teaching others. He tries to force a particular perspective, emphasizing the importance of his role while fostering dependency rather than sharing knowledge. This seems driven by a fear of losing his job.
My primary focus is backend development, where I assist developers and solve infrastructure challenges. However, I’m so effective in this role that I often end up boxed into it. I’ve been making an effort to expand into frontend development to broaden my expertise, but this colleague operates in that space and isn't the only one who has made it difficult for others to gain traction.
I agree with another commenter that this doesn't tell the entire story, but it tells almost all of it. Nowadays, I discover some new piece of software, visit the Documentation section of its website, and the first thing I see is `How to build SuperMung on the Whizzbang 47 using Mark Williams C'. I have no idea what SuperMung is for, how to use it, what errors I might make, and how to install it on Debian. Similarly, I go to the website for a new programming language, see some examples that give me little insight into what it is for, and find not even an incomplete language specification.
Proper documentation leads me by the hand, starting on what the software is for, what platforms it runs on, some examples of its use (including examples that show how it is useful for solving real-life problems), a thorough tutorial on how to use it, and finally a complete and properly indexed/searchable reference.
Back in the 1980s, I got myself in trouble: I promised a 100-page manual for a software system I had written, and I decided to do it in the then-new TeX. But this was before The TeXBook was published. So I learned TeX by reading the literate source for the code. The manual was duly ready on time, and served the literally thousands of students who relied on it for the next few years.
But when I finally got a copy of The TeXBook, I was astonished by how little I had actually known about using TeX. I had presumably been mostly using it to answer questions such as “why doesn't this work?”, and a lot of the overall principles had simply not been apparent to me. Once I had learned TeX properly, I learned a great deal about how it all worked by going back and reading the literate source. Knuth is a brilliant (if highly idiosyncratic) programmer.
My point here is to emphasize that when someone releases software, their job is not done unless people can learn to use it. That doesn't just mean completeness and accuracy, but a through-line, apparent to the reader, from learning what it does all the way to mastering it, along with the kind of reference information needed when using it.
This article is primarily about making documentation more effective for learning, not about replacing technical completeness. The best approach combines both perspectives rather than treating them as an either/or proposition.
compare https://docs.divio.com/documentation-system/
Signals And Threads (a Jane Street podcast) had an interesting discussion about documentation [0]. There was also an interesting reference to literate documentation (I think similar to Jupyter notebooks but as documentation).
[0] https://signalsandthreads.com/writing-technically/
Good docs are rare like unicorns with a glowing horn.
It doesn't seem to move the needle like a shipped feature does, requires guessing other peoples' perspectives, involves devoted time and effort (that could, you know, be spent on actually useful things) and the effects of not doing it are invisible (but real: user rage, frustration and wasted time).
Only when the importance of good docs is understood will any effort be invested into it. It should be important if the goal is to have more people using something.