AWS, Rust std.
Ask HN: What is example of good documentation in your opinion?
31–40 of 71 posts
Re: Ask HN: What is example of good documentation in your opinion?
#32Postgres docs have always been top notch https://www.postgresql.org/docs/current/index.html
It's a shame that Google still seems to favour Postgres 9.x documentation and blogspam over the current documentation.
Re: Ask HN: What is example of good documentation in your opinion?
#33I find Mozilla documentation is very good - eg: https://developer.mozilla.org/en-US/docs/Web/HTTP
Re: Ask HN: What is example of good documentation in your opinion?
#34Perl man pages. Was working with Perl on a job and had no internet or outside connection. The man pages are outstanding.
Re: Ask HN: What is example of good documentation in your opinion?
#35Spack's official documentation is fantastic:
Re: Ask HN: What is example of good documentation in your opinion?
#36The 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.
Re: Ask HN: What is example of good documentation in your opinion?
#37While 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 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)
Re: Ask HN: What is example of good documentation in your opinion?
#38Pandas - https://pandas.pydata.org/docs/
Re: Ask HN: What is example of good documentation in your opinion?
#39Microsofts 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"Re: Ask HN: What is example of good documentation in your opinion?
#40Definitely not the vendor we use at work. If I click the "Help" button, it's basically a line like this for every field:
"Choose the $Ambiguous policy from the $Ambiguous policy dropdown".
Geez, thanks.