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.
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 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.
> 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.
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.
I love Django. I was inspired this summer to start an open source project for gaps in their docs like setting up a local development environment, using React for the frontend, deploying to Heroku/AWS, adding Google Analytics, etc.
I help out on the Unofficial Django Discord a lot. I have to constantly tell people to go do the tutorial on djangoproject.com instead of some rando youtubers totally broken tutorial. It's crazy how many incompetent youtube tutorials there are just for django!
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 it to be in (for example, the methods available for the list type aren't in the Built-in Types page even though lists are mentioned there, nor in its own dedicated list page, but are instead in a "More on Lists" section in the Data Structures page which apparently isn't linked in the types page at all)
Completely agree. The Python docs are almost unreadable to me. Every time I’m looking for something (a function parameter, example usage, etc.) it’s the same:
- 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.
Microsofts referencesource. Meaning published source for closed source libraries. No amount of documentation beats being able to see for yourself not just what the software will do not only the documented/supported scenarios but also in undocumented ones.
But just because the Microsoft API documentation is always very meaningless. This could be from their docs:
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"
Rust was already mentioned, but I want to call out the compiler error messages specifically. That's putting documentation where you need it exactly when you need it most and it's a triumph.
I love the documentation for Ansible. You have a good amount of well thought out examples, very well written explanations for things, and links to other related functions.
Not concise, but the manual of the COHERENT Unix clone, developed by Mark Williams Company between the 1980s and the early 1990s, is what made me grok Unix: http://www.nesssoftware.com/home/mwc/manual.php
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?
Two long-form examples for programs I don't see here yet. Note that they won't necessarily be great for other projects (e.g. for a library, where you as the user will probably need/expect "on-point documentation" for specific details while working with the product in question), but as a wholistic introduction to a specific tool, I've yet to see much better examples.
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.
Vuejs documentation. They have an API reference and a guide. Can go to 0 to using the framework in no time, and contains all you could possibly need once you dive deeper.
I always liked Cisco documentation, besides the documentation for each product in great detail, as it was in the 80's, everything in PDF, you also have links to manuals of a bunch of technology that the product support, just not the product. Well structure and organized. I miss that in many products and software nowadays.
Lua's manual. One flat page with everything. Language, standard library, C API, and even the complete syntax. The only thing it needs is the table of contents prepended. Possibly lacking examples which is something you asked for.
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.