Ask HN: What is example of good documentation in your opinion? I know its kinda generic question, but what technical documentation you would point to as well written, concise, with good examples etc.. Something that really stands out. |
Ask HN: What is example of good documentation in your opinion? I know its kinda generic question, but what technical documentation you would point to as well written, concise, with good examples etc.. Something that really stands out. |
Clear and easy to follow language with awesome examples. I really like that additional concepts are explained as well.
"Choose the $Ambiguous policy from the $Ambiguous policy dropdown".
Geez, thanks.
And to manage/search documentation I like docsets and Zeal a lot.
The tutorials get you off the ground and the Docs are detailed enough to take you safely over the long grass.
2. Tutorials for beginners
3. Advanced guides.
AWS for breadth and organization
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 Instruments, Fairchild and many others. Also many European companies had excellent technical documentation, e.g. Philips, Thomson, Siemens, SGS-ATES and many others. Many ancient manuals have been preserved at bitsavers.org and at a few other similar sites.
I believe that the FreeBSD manual from 1995 was better than any later operating system manual from the point of view of the completeness of its coverage of the existing features. The Gentoo manual before 2005 was also excellent. Both FreeBSD and Gentoo have good documentation even today, but nevertheless their manuals have not been kept completely up-to-date, so now they contain various holes about features that are not covered, unlike in the original complete manuals.
Before the Internet, for those who were not living in USA it could be very difficult to obtain many of the manuals and datasheets published by US companies, except perhaps at their booths at some international trade fairs.
After the Internet appeared, I was very happy that suddenly it became trivial to obtain any technical documentation, even if in the beginning that was done by FTP on dial-up modems at speeds as low as 2400 b/s.
Unfortunately, the time when it became easy to obtain technical documentation has coincided perfectly with the time when there was a tremendous decline in the quality of the technical documentation. Now it is easy to obtain technical documentation, but its content is much less valuable.
In many cases, e.g. for embedded processors and various complex interface integrated circuits, until you perform some tests on development boards you cannot be completely sure about how certain things work, instead of being able to predict any behavior based on the documentation. Moreover, if a company provides some example programs, they frequently contain valuable information that is missing from the manuals or datasheets.
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.
Great examples. Clearly noting what versions things changed. Ability to switch versions at the click of a button.
- 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.
- Clear description, signature, types for parameters, return values.
- Examples, which will often cover edge cases.
- Separate page for each method
- A clear changelog section to document changes across versions.
Python on the other hand, gets a single sentence.
class SomethingProvider: "Provides functionality for communication with something"
property string SomethingUrl: "Gets/sets the URL for the something endpoint"
function Initialize(string[] roles): "Initializes Something-Provider with the given roles"There’s always good explanation and examples within their docs
https://docs.ansible.com/ansible/latest/collections/ansible/...
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?
I would say that mine[1] created via GitBook is not terrible either, I usually tend to provide more generic instructions and multiple ways of doing one thing, so that it doesn't get out of date too quick.
The other commenter mentions docs from the past being better, but I have always found Java’s docs to be particularly atrocious.
No examples, and barely any information beyond a type signature.
When I open up a project’s docs and they have that same Java html formatting, I get that faraway stare…
Most importantly it has interactive examples that let you understand through doing and playing, rather than just reading.