3 ms·

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 updat

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

3 ms·

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 updat

by andix 4y ago

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.