3 ms·

As much as I appreciate the value of good documentation, forcing most developers to write documentation would be less than worthless. In part because most peopl

As much as I appreciate the value of good documentation, forcing most developers to write documentation would be less than worthless. In part because most people are no good at writing to communicate complex ideas to others. Developers are no better, and may in fact be worse. While they might understand the complex ideas, in trying to explain them to others they run into the Curse of Knowledge. With no skill in turning ideas into communication, the output is at best a first draft of something that might be input into useful documentation.

andix 4y ago
Im not talking about end user documentation. More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. This is really often missing, I’ve seen it often that a developer quits, and then it takes weeks or months until the next bugfix can be deployed into production.
- cratermoon 4y ago
  > More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. That still implies writing to an audience other than yourself, and the Curse of Knowledge still applies. In many ways, it's much worse, because it's easy to assume that because the document is for a technical audience that the reader will know as much and have the same context as the author, and easy to include less supporting material. I look at StackOverflow and see how many questions are technically answered in the documentation, but in fact do not prevent the question from coming up. It's not the the questioner can't understand or the question is stupid, it's that the mental model of the reader and writer don't match up. Of course it's much worse if, as in your example, the knowledge is in one person's head. That's a related problem, and having something is better than nothing. Even with some documents, cases still arise where there's a missing piece of information that the document author didn't record. The author understood what the document meant, not realizing it is only understandable given some knowledge the author did not provide.
  - andix 4y ago
    So you’re basically saying most developers are unable to write documentation?
    - cratermoon 4y ago
      I'd say the proportion of developers that are able to write good, readable, documentation is about the same proportion as those who can write good, readable code.
bmitc 4y ago
> In part because most people are no good at writing to communicate complex ideas to others. Developers are no better, and may in fact be worse. The entire point of writing software is to communicate complex ideas to others.
- cratermoon 4y ago
  "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." – Martin Fowler. Most programers are no good at writing code the communicates to other humans. They write code that computers can understand, which is a completely different skill.

andix 4y ago

Im not talking about end user documentation. More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. This is really often missing, I’ve seen it often that a developer quits, and then it takes weeks or months until the next bugfix can be deployed into production.

cratermoon 4y ago
> More about how to configure and operate the software. How to add features, how to debug issues. How to deploy updates and so on. That still implies writing to an audience other than yourself, and the Curse of Knowledge still applies. In many ways, it's much worse, because it's easy to assume that because the document is for a technical audience that the reader will know as much and have the same context as the author, and easy to include less supporting material. I look at StackOverflow and see how many questions are technically answered in the documentation, but in fact do not prevent the question from coming up. It's not the the questioner can't understand or the question is stupid, it's that the mental model of the reader and writer don't match up. Of course it's much worse if, as in your example, the knowledge is in one person's head. That's a related problem, and having something is better than nothing. Even with some documents, cases still arise where there's a missing piece of information that the document author didn't record. The author understood what the document meant, not realizing it is only understandable given some knowledge the author did not provide.
- andix 4y ago
  So you’re basically saying most developers are unable to write documentation?
  - cratermoon 4y ago
    I'd say the proportion of developers that are able to write good, readable, documentation is about the same proportion as those who can write good, readable code.

bmitc 4y ago

> In part because most people are no good at writing to communicate complex ideas to others. Developers are no better, and may in fact be worse. The entire point of writing software is to communicate complex ideas to others.

cratermoon 4y ago
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." – Martin Fowler. Most programers are no good at writing code the communicates to other humans. They write code that computers can understand, which is a completely different skill.