51–60 of 71 posts
And to manage/search documentation I like docsets and Zeal a lot.
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 au…
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?
While Python is "the second best language for any task", I think the Python standard library documentation is second-to-none: https://docs.python.org/3/library/index.html
I'll have to disagree. Many things about it are a constant source of annoyance for me, such as the fact that function arguments and return types aren't listed in a standard format with a short description of each and instead they expect you to read the entire (often quite large) paragraph of text below each function to find that information, and the fact that a lot of information isn't found in the page you'd expect…
- I Google it
- I look for the official docs page (usually 5th or 6th result)
- I tried to find my answer but don’t understand the organization and cannot find the correct keywords to Ctrl-F
- I go back to my Google search frustrated and try to find a suitable StackOverflow answer instead
In comparison with Go the official docs are usually the first or second Google results and the docs are easy to navigate and understand.
Django is one of the gold standards for me. Great examples. Clearly noting what versions things changed. Ability to switch versions at the click of a button. https://docs.djangoproject.com/en/4.1/
The more you go into the past, the better technical documentation you will find. The documentation from the nineties of the 20th century was much better than the later documentation, and that from the seventies and the eighties was probably the peak, e.g. the various manuals of the Hewlett-Packard instruments, and also various manuals from DEC, IBM, Tektronix, National Semiconductor, Motorola, Intel, AMD, Texas Instr…
The past was also a time when professional technical writers were employed to write excellent documentation. It’s still been my experience that the best documentation for a product that I’ve worked on was written by dedicated staff. They approached it from the perspective of the customer and asked thoughtful questions whose answers were reflected in the resulting writing (and many times made me reconsider design decisions). I think ultimately, the ease with which online documentation could be updated (by comparison with the finality of print) led MBAs to shift writing responsibilities to engineering as a cost-saving strategy.