4 ms·

This is a read vs write optimisation trade-off. If a senior engineer would need to write down all it knows and all things that were considered for a specific im

by spockz 7y ago

This is a read vs write optimisation trade-off. If a senior engineer would need to write down all it knows and all things that were considered for a specific implementation or project he would have to spent a lot of time writing. Especially if the writing needs to be clear for some junior just joining the company. If instead, only the high over view is written down the person can be relied upon the fill in the nitty gritty details without having to spent years writing. (It can also be of course that we just lack a sufficiently efficient fork of dumping our mental context for others to digest.)

yoz-y 7y ago
I think there is also a problem with too much documentation. If you want do document too much, the docs will get too tedious to read and crucial information can be missed.
- perl4ever 7y ago
  I started working in a kind of non-technical department, and someone had developed a procedure for making some database updates which used to be done manually through a web page, and the procedure for this "automated" method went through like 50 pages. After doing it two or three times I'd memorized it. But if I was documenting it, I would be like "here's 5 bullet points" and they would be prompts to fill in the details. It depends on the audience, but the way I prefer to write documentation is I think of how I discovered all the stuff that was not obvious and try to provide starting points to each area of knowledge. In some environments, people will write so much documentation that you can't see the structure, and when you see repetitive sections, you can't tell what the difference is without actually diffing it. There is an enormous amount of formulaic documentation that is 90% boilerplate and almost completely fails to focus on what people need to know. So many tools have been developed to easily produce stuff that looks like documentation but doesn't have any content and then using them is compulsory, but substance is not. I've been unimpressed with the Microsoft online documentation I've had to look up recently.
  - yoz-y 7y ago
    Indeed, I really dislike java doc style of documentation which forces you to explicitly state a short description, then parameters and then a return value. For many simple functions a return value documentation which mentions the parameters would be amply sufficient.

by spockz 7y ago

yoz-y 7y ago

I think there is also a problem with too much documentation. If you want do document too much, the docs will get too tedious to read and crucial information can be missed.

perl4ever 7y ago
I started working in a kind of non-technical department, and someone had developed a procedure for making some database updates which used to be done manually through a web page, and the procedure for this "automated" method went through like 50 pages. After doing it two or three times I'd memorized it. But if I was documenting it, I would be like "here's 5 bullet points" and they would be prompts to fill in the details. It depends on the audience, but the way I prefer to write documentation is I think of how I discovered all the stuff that was not obvious and try to provide starting points to each area of knowledge. In some environments, people will write so much documentation that you can't see the structure, and when you see repetitive sections, you can't tell what the difference is without actually diffing it. There is an enormous amount of formulaic documentation that is 90% boilerplate and almost completely fails to focus on what people need to know. So many tools have been developed to easily produce stuff that looks like documentation but doesn't have any content and then using them is compulsory, but substance is not. I've been unimpressed with the Microsoft online documentation I've had to look up recently.
- yoz-y 7y ago
  Indeed, I really dislike java doc style of documentation which forces you to explicitly state a short description, then parameters and then a return value. For many simple functions a return value documentation which mentions the parameters would be amply sufficient.