6 ms·

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. Article

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.

fn-mote 2y ago
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".
dangrape123 2y ago
[dead]
cjfd 2y ago
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.
- mjw1007 2y ago
  The bad documentation I come across often shows every sign of having taken the advice from this article (and others like it) to heart. The trouble is that the advice doesn't include ways to make sure your documentation actually covers everything it has to. What this article says is that you should have « "API documentation" for every user-facing part of your project. » That commonly leads to "reference" pages which are very little better than the autogenerated documentation the author dismisses. The main problems tend to be that behaviour that isn't controlled by a specific command or function or configuration setting doesn't get documented at all, and that commands with complex behaviour get described using terms that themselves need further definition which isn't provided anywhere.
  - AlienRobot 2y ago
    My experience is that the main problem with online documentation is that it doesn't include links to separate tutorials, but has plenty of links to more documentation, leading you to wander from page to page without destination trying to find that one page that actually explains what you're trying to do or infer it from fragments of information scattered around the documentation. For example, in Qt you have a view class, a model class, and a selection model class, and none of their pages tell you how to actually select something programmatically. You have to guess or ask ChatGPT these days.
- sourcedemand 2y ago
  > The source code satisfies this demand. If it's available... Also, it's much harder to parse multiple files than one doc. Been there, done that, aplenty. Yes, I can find the answer, but that isn't sufficiently going to make it easier. Plus, if one admits the docs are bad because "the source answers that type of in-depth question", then are the docs not still bad?
  - cjfd 2y ago
    Sure, if the docs are bad, the docs are bad ;-). Jokes aside, though, I think the nice thing that this article does is pointing out various common ways in which the docs can be bad. My 'favorite' one is having docstrings for documentation. They take quite a bit of time to write, clutter the code with helpful information like 'the method get_heigth, gets the height' and if they are the only thing that is shipped as information use users severely lacking. Another thing to note is that what this article lists as good docs actually cost a lot of time to create. Perhaps this is why people settle for the less than helpful alternatives. I think, though, that it is better to provide a subset of the good docs rather than useless docs that just annoy people.
Swizec 2y ago
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.
- kkapelon 2y ago
  You actually need four https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/ Explanation (why, what) reference (API spec) tutorials How to guides
  - Swizec 2y ago
    Thanks! Knew I was missing something. I guess in my mind tutorials and howtos merged :D
  - ranit 2y ago
    Right! The good old days when the software used to come in a box with several varied width books containing all these Four, and one named Getting Started. This same set could be easily "transposed" to the contemporary world of web. With all the proper indexing. Why is this "art" "lost" for most of the software :-( ... BTW, one Excellent incarnation of this documentation art is on the front page right now: https://news.ycombinator.com/item?id=43381627 https://news.ycombinator.com/item?id=43381627
    - cogman10 2y ago
      > Why is this "art" "lost" for most of the software. Before the internet, the printed book was all you really got. That meant the company distributing the software had to hire technical writers who'd work with the software devs to create all of this, send it to an editor, and ultimately get published. We no longer live in an era where tech companies hire tech writers. Software documentation lacking is something that can and limp along with jira cases and support services sold rather than trying to put in the upfront effort to fix everything. Now, for open source software, hate to say it but the docs have always been pretty crap. Certainly some stands out (usually when the business model was around providing services on top of open source software), but nobody is really paying anyone and few people really want to do that sort of free labor.
ChrisMarshallNY 2y ago
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/ https://littlegreenviper.com/leaving-a-legacy/
- Sparkyte 2y ago
  Absolutely this! If I have to use a search box to find docs and not the navigation pane you know you're doing something wrong with your docs.
  - ChrisMarshallNY 2y ago
    I’m hoping that LLMs may be helpful, here. Sort of like a “documentation concierge” service. Like going to the reference desk in a local library, and asking The Librarian to help you find some information.
    - Sparkyte 2y ago
      I believe so. I am also hoping it can just pull in repositories and tell me more about the code and history relating to it. There is a lot of potential to this. TLDRs are needed for code, LLMs will be an excellent replacement.
Sparkyte 2y ago
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.
mixermachine 2y ago
I can confirm this from the producer side. The documentation is often neglected. I got fed up with the Word docx (with code examples) we sent out to our customers and replaced it with a hosted Docusaurus markdown documentation. It is a lot of work to transfer the knowledge to a the new place. It is a lot of work to keep the documentation up-to-date. It is also a lot of work to formulate things in a widely understandable way with screenshots and good examples. Still I would do the same refactoring again. While the documentation is still not perfect, our customers now comment that it truly helps them to get going fast with our product. A search function is also very helpful. Our QA team does follow the integration instructions in the documentation when a major change is released (so "putting somebody in the student's place" does work for us). It of course takes time.
madsbuch 2y ago
> The first duty of your documentation is to be complete and correct. It is probably unrealistic to expect documentation to be complete as it is not clear where the border on inclusiveness goes. Take eg. AWSs node packages. Here they spend words recommending using async / await which IMHO is firmly outside the scope of library docs. I am curious on what you feel is missing? is it elements concrete to the piece of software you use, or is it pieces that can be deemed expected knowledge from a professional software developer.
- mjw1007 2y ago
  The former.
ajnin 2y ago
Yes, using the analogy used in the article, programmers are not the students trying to learn how to drive, they are the professional engineers and mechanics that build and maintain the cars. They don't need teaching, they need technical documentation. They already should possess the know-how to transform such documentation into practical applications. The "be a teacher" motto is how you end up with "documentation" that is a bunch of examples of how to do various things and then no exhaustive and rigorous technical reference or even none at all. And then good luck scouring blog posts and StackOverflow or ask help on IRC (pray it's not on Discord) in the hellscape that has become Internet search if you want to do anything not in the examples.

fn-mote 2y ago

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".

dangrape123 2y ago

[dead]

cjfd 2y ago

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.

mjw1007 2y ago
The bad documentation I come across often shows every sign of having taken the advice from this article (and others like it) to heart. The trouble is that the advice doesn't include ways to make sure your documentation actually covers everything it has to. What this article says is that you should have « "API documentation" for every user-facing part of your project. » That commonly leads to "reference" pages which are very little better than the autogenerated documentation the author dismisses. The main problems tend to be that behaviour that isn't controlled by a specific command or function or configuration setting doesn't get documented at all, and that commands with complex behaviour get described using terms that themselves need further definition which isn't provided anywhere.
- AlienRobot 2y ago
  My experience is that the main problem with online documentation is that it doesn't include links to separate tutorials, but has plenty of links to more documentation, leading you to wander from page to page without destination trying to find that one page that actually explains what you're trying to do or infer it from fragments of information scattered around the documentation. For example, in Qt you have a view class, a model class, and a selection model class, and none of their pages tell you how to actually select something programmatically. You have to guess or ask ChatGPT these days.
sourcedemand 2y ago
> The source code satisfies this demand. If it's available... Also, it's much harder to parse multiple files than one doc. Been there, done that, aplenty. Yes, I can find the answer, but that isn't sufficiently going to make it easier. Plus, if one admits the docs are bad because "the source answers that type of in-depth question", then are the docs not still bad?
- cjfd 2y ago
  Sure, if the docs are bad, the docs are bad ;-). Jokes aside, though, I think the nice thing that this article does is pointing out various common ways in which the docs can be bad. My 'favorite' one is having docstrings for documentation. They take quite a bit of time to write, clutter the code with helpful information like 'the method get_heigth, gets the height' and if they are the only thing that is shipped as information use users severely lacking. Another thing to note is that what this article lists as good docs actually cost a lot of time to create. Perhaps this is why people settle for the less than helpful alternatives. I think, though, that it is better to provide a subset of the good docs rather than useless docs that just annoy people.

Swizec 2y ago

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.

kkapelon 2y ago
You actually need four https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/ Explanation (why, what) reference (API spec) tutorials How to guides
- Swizec 2y ago
  Thanks! Knew I was missing something. I guess in my mind tutorials and howtos merged :D
- ranit 2y ago
  Right! The good old days when the software used to come in a box with several varied width books containing all these Four, and one named Getting Started. This same set could be easily "transposed" to the contemporary world of web. With all the proper indexing. Why is this "art" "lost" for most of the software :-( ... BTW, one Excellent incarnation of this documentation art is on the front page right now: https://news.ycombinator.com/item?id=43381627 https://news.ycombinator.com/item?id=43381627
  - cogman10 2y ago
    > Why is this "art" "lost" for most of the software. Before the internet, the printed book was all you really got. That meant the company distributing the software had to hire technical writers who'd work with the software devs to create all of this, send it to an editor, and ultimately get published. We no longer live in an era where tech companies hire tech writers. Software documentation lacking is something that can and limp along with jira cases and support services sold rather than trying to put in the upfront effort to fix everything. Now, for open source software, hate to say it but the docs have always been pretty crap. Certainly some stands out (usually when the business model was around providing services on top of open source software), but nobody is really paying anyone and few people really want to do that sort of free labor.

ChrisMarshallNY 2y ago

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/ https://littlegreenviper.com/leaving-a-legacy/

Sparkyte 2y ago
Absolutely this! If I have to use a search box to find docs and not the navigation pane you know you're doing something wrong with your docs.
- ChrisMarshallNY 2y ago
  I’m hoping that LLMs may be helpful, here. Sort of like a “documentation concierge” service. Like going to the reference desk in a local library, and asking The Librarian to help you find some information.
  - Sparkyte 2y ago
    I believe so. I am also hoping it can just pull in repositories and tell me more about the code and history relating to it. There is a lot of potential to this. TLDRs are needed for code, LLMs will be an excellent replacement.

Sparkyte 2y ago

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.

mixermachine 2y ago

I can confirm this from the producer side. The documentation is often neglected. I got fed up with the Word docx (with code examples) we sent out to our customers and replaced it with a hosted Docusaurus markdown documentation. It is a lot of work to transfer the knowledge to a the new place. It is a lot of work to keep the documentation up-to-date. It is also a lot of work to formulate things in a widely understandable way with screenshots and good examples. Still I would do the same refactoring again. While the documentation is still not perfect, our customers now comment that it truly helps them to get going fast with our product. A search function is also very helpful. Our QA team does follow the integration instructions in the documentation when a major change is released (so "putting somebody in the student's place" does work for us). It of course takes time.

madsbuch 2y ago

> The first duty of your documentation is to be complete and correct. It is probably unrealistic to expect documentation to be complete as it is not clear where the border on inclusiveness goes. Take eg. AWSs node packages. Here they spend words recommending using async / await which IMHO is firmly outside the scope of library docs. I am curious on what you feel is missing? is it elements concrete to the piece of software you use, or is it pieces that can be deemed expected knowledge from a professional software developer.

mjw1007 2y ago
The former.

ajnin 2y ago

Yes, using the analogy used in the article, programmers are not the students trying to learn how to drive, they are the professional engineers and mechanics that build and maintain the cars. They don't need teaching, they need technical documentation. They already should possess the know-how to transform such documentation into practical applications. The "be a teacher" motto is how you end up with "documentation" that is a bunch of examples of how to do various things and then no exhaustive and rigorous technical reference or even none at all. And then good luck scouring blog posts and StackOverflow or ask help on IRC (pray it's not on Discord) in the hellscape that has become Internet search if you want to do anything not in the examples.