The manual for my dishwasher. What I learned from it was that technical writing is a skill and that it does not come from technical knowledge alone.
The best documentation knows its audience and what they want to know. I quite like cppreference and usually ISA documentation is quite good. But this is because I am part of their target audience.
The worst documentation is the one which has entirely lost sight of its audience. Particularly offenses are it being a mix of tutorial and reference, which is filled with explanatory prosa potentially even serving as a first introduction to the given topic.
Cppreference is about the worst way to learn C or C++ and if it weren't it would be far less useful to me. Documentation writers have to know their audience first and foremost. There is a place for walkthroughs and tutorials, but they can not replace an actual language reference.
That’s genuinely interesting. In my experience manuals for home electronics are universally terrible. Would you be able to share a link to this counter example?
The best documentation knows its audience and what they want to know. I quite like cppreference and usually ISA documentation is quite good. But this is because I am part of their target audience.
The worst documentation is the one which has entirely lost sight of its audience. Particularly offenses are it being a mix of tutorial and reference, which is filled with explanatory prosa potentially even serving as a first introduction to the given topic.
Cppreference is about the worst way to learn C or C++ and if it weren't it would be far less useful to me. Documentation writers have to know their audience first and foremost. There is a place for walkthroughs and tutorials, but they can not replace an actual language reference.