3 ms·

Ask HN: What do you consider the gold standard for software documentation?

2 points by Jimmc414 4y ago

Postgresql's documentation seems like it would be a good model for a software company, perhaps. https://www.postgresql.org/files/documentation/pdf/15/postgresql-15-US.pdf

themerone 4y ago
I agree, Postgresql has been my gold standard for more than a decade. The documentation is an excellent user manual and reference guide. This is a rare combination. Most databases I've worked with provide deeply technical references that are only good for someone already experienced with the product. With most software vendors you are lucky to get some always out of date tutorial blogs to accompany their api docs. The Postgresql documentation is good enough to teach someone SQL from scratch.
- fargle 4y ago
  I don't know if it's "gold standard" but I have the same feeling about the GNU CPP (c preprocessor) and GNU Make manuals. There are very few good sources about either using make or CPP macros. These manuals are more than just how to use gmake or the CPP stage of gcc. They actually are great references into how make works and how to write macros in C. I find myself referring to both frequently, so at some level, they must be considered far above the average. https://www.gnu.org/software/make/manual/make.html https://www.gnu.org/software/make/manual/make.html https://gcc.gnu.org/onlinedocs/gcc-12.1.0/cpp/ https://gcc.gnu.org/onlinedocs/gcc-12.1.0/cpp/ In the 1980s, maybe earlier, many computer software packages included manuals of this ilk. I remember a couple of examples, "DBASE-IV" and "Mark Williams Let's C" compiler, "Commodore BASIC". They not only documented the specific tool, but also the entire theory of databases, "C" programming, or BASIC and the coding useful things on the PET/C64. It's amazing how good the quality of the technical writing was as well as how broad the subject matter was. It was literally everything you needed to know to solve your problems - not just how to use their tool. I think it had to be when computers and these applications were so new to so many.
dieselgate 4y ago
I’m a big fan of the Mozilla MDN web docs; alas am not fluent with postgresql
johncoltrane 4y ago
Vim's online documentation (in the original meaning of "online") is second to none in the text editor/IDE space. - A quick and easy interactive tutorial to teach you the absolute basics: $ vimtutor. No prerequisite whatsoever. - An extensive tutorial that takes you from noob to wherever you want to go in a gentle and iterative way, the user manual: :help usr_toc. This one is pretty much the natural next step after vimtutor if you ever want to use Vim efficiently. Too many people think they are smart enough so they skip it. They are wrong. Even vimtutor is not a prerequisite. - A heavily cross-linked reference that covers literally everything, the reference manual: :help reference_toc. This one can be anything from extremely detailed to very terse. You get there when you are not sure about something are to take a deep dive on a specific subject. In general, this part of the documentation makes more sense if you went through the user manual first.
booboofixer 4y ago
Havent read/seen a lot but from a noob's perspective, node.js docs were an easy read. Git manual online is also easy to navigate but i suppose the simplicity of the tool itself helps.
lovelearning 4y ago
The reference docs for Java Standard Edition APIs and MSDN Win32 APIs were clear, comprehensive, and unambiguous. The behaviors of those platforms were also predictable and deterministic. At a time when the internet was a luxury and there weren't Google and SO, I was able to learn and use Win32 APIs just from their reference docs and guides. In sharp contrast to Java's docs are Android's terrible docs. As a Java programmer, I had assumed Android's docs and behavior would be of equally high quality. But time and again, Android's platform had a a way of springing surprises that weren't documented anywhere. More than a decade has passed but the activity lifecycle's behavior and docs remain as ambiguous today in 2022 as they were in 2010!

2 points by Jimmc414 4y ago

Postgresql's documentation seems like it would be a good model for a software company, perhaps. https://www.postgresql.org/files/documentation/pdf/15/postgresql-15-US.pdf

themerone 4y ago

I agree, Postgresql has been my gold standard for more than a decade. The documentation is an excellent user manual and reference guide. This is a rare combination. Most databases I've worked with provide deeply technical references that are only good for someone already experienced with the product. With most software vendors you are lucky to get some always out of date tutorial blogs to accompany their api docs. The Postgresql documentation is good enough to teach someone SQL from scratch.

fargle 4y ago
I don't know if it's "gold standard" but I have the same feeling about the GNU CPP (c preprocessor) and GNU Make manuals. There are very few good sources about either using make or CPP macros. These manuals are more than just how to use gmake or the CPP stage of gcc. They actually are great references into how make works and how to write macros in C. I find myself referring to both frequently, so at some level, they must be considered far above the average. https://www.gnu.org/software/make/manual/make.html https://www.gnu.org/software/make/manual/make.html https://gcc.gnu.org/onlinedocs/gcc-12.1.0/cpp/ https://gcc.gnu.org/onlinedocs/gcc-12.1.0/cpp/ In the 1980s, maybe earlier, many computer software packages included manuals of this ilk. I remember a couple of examples, "DBASE-IV" and "Mark Williams Let's C" compiler, "Commodore BASIC". They not only documented the specific tool, but also the entire theory of databases, "C" programming, or BASIC and the coding useful things on the PET/C64. It's amazing how good the quality of the technical writing was as well as how broad the subject matter was. It was literally everything you needed to know to solve your problems - not just how to use their tool. I think it had to be when computers and these applications were so new to so many.

dieselgate 4y ago

I’m a big fan of the Mozilla MDN web docs; alas am not fluent with postgresql

johncoltrane 4y ago

Vim's online documentation (in the original meaning of "online") is second to none in the text editor/IDE space. - A quick and easy interactive tutorial to teach you the absolute basics: $ vimtutor. No prerequisite whatsoever. - An extensive tutorial that takes you from noob to wherever you want to go in a gentle and iterative way, the user manual: :help usr_toc. This one is pretty much the natural next step after vimtutor if you ever want to use Vim efficiently. Too many people think they are smart enough so they skip it. They are wrong. Even vimtutor is not a prerequisite. - A heavily cross-linked reference that covers literally everything, the reference manual: :help reference_toc. This one can be anything from extremely detailed to very terse. You get there when you are not sure about something are to take a deep dive on a specific subject. In general, this part of the documentation makes more sense if you went through the user manual first.

booboofixer 4y ago

Havent read/seen a lot but from a noob's perspective, node.js docs were an easy read. Git manual online is also easy to navigate but i suppose the simplicity of the tool itself helps.

lovelearning 4y ago

The reference docs for Java Standard Edition APIs and MSDN Win32 APIs were clear, comprehensive, and unambiguous. The behaviors of those platforms were also predictable and deterministic. At a time when the internet was a luxury and there weren't Google and SO, I was able to learn and use Win32 APIs just from their reference docs and guides. In sharp contrast to Java's docs are Android's terrible docs. As a Java programmer, I had assumed Android's docs and behavior would be of equally high quality. But time and again, Android's platform had a a way of springing surprises that weren't documented anywhere. More than a decade has passed but the activity lifecycle's behavior and docs remain as ambiguous today in 2022 as they were in 2010!