This is a nice article (though i think a bit too wordy). Note that what it calls "tutorial", "how-to guides" and "explanation" is sometimes called "guides", "howtos" and "rationale".
As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, controls, etc) and for each group there is an "overview" section (e.g. Windows introduces the windows concept), then a reference (often split in several parts itself) and finally one or two examples (though that was optional).
The help itself didn't have "howtos" or "rationales" but those were available through MSDN (later at least) as knowledge base articles.
(modern winapi documentation is a mess on that regard, especially if you do not already have a vague knowledge of what you are looking for, because even though it is largely the same text, they have split and moved things around too much and put irrelevant distracting links everywhere)
On the Unix world, the original X11 documentation follows a similar pattern, though for other more recent projects there is usually a very one-sided approach: as the article says, most projects only provide API references and perhaps a single (often unfinished) tutorial.
GNU projects usually have documentation in texinfo which is laid out as a book and is often very good (most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output nor really the info format itself that has more usable viewers like tkinfo). It also has a similar approach as the Win3.1/95 docs, though i think the lines between "guide" and "reference" are often blurred. This largely depends on the project though (e.g. the glibc manual has these better divided, whereas the bash manual tends to be more "blurry"). Also i'm not fan of GNU's style of function references - i prefer the more common/manpage-like style where for each function/macro/struct/etc you have an isolated page a very brief description about its purpose, its declaration, a list of what each parameter (for functions and macros) does, its return value (if any), a detailed description (if necessary), any requirements (e.g. headers, for APIs with multiple headers) and links to other relevant functions and guides.
Also i find examples for each function to be nice though this is even more rare than guides.
As a sidenote, i loathe autogenerated documentation and "docgen comments" in source code (and not only because they tend to enforce the "reference-only" approach). I think those should be totally separate and not pollute the code with documentation (especially headers as that makes it harder to read the headers that also act as a quick overview for an API).
Though having a tool to automatically check docs and sources for mismatches (missing functions and/or functions with wrong declarations in the docs) is helpful. But i'm not aware of anything that does that.
> I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library
You might be right but I don't remember being impressed with Microsoft's documentation. Half the time if was missing APIs for common useful tasks (there was a big community around demoing undocumented APIs -- granted some were genuinely only intended for internal use but there were some APIs that really should have been documented but weren't) and some of the example code Microsoft did publish was next to useless.
There was one occasion when I was teaching myself DDE (anyone else remember that?) and the example looked a bit weird because the example application would launch and call itself. "ok," I thought, "I'm obviously missing some logic when reading through. Maybe I should just run it to test it's behaviour." Five minutes later I was forced to reboot after my suspicions were confirmed -- their official DDE example was literally just a fork bomb. Well done Microsoft /s
However I did learn a valuable lesson that day: never trust example code.
I do not think they ever did a good job when it comes to examples, especially in the earlier days. Others like Borland were much better there.
But ever since 3.1 docs you could learn everything you wanted from the help file alone (3.0 help files were reference only) and i mainly refer to their structure. The content was sometimes a miss (though the worst i can remember is not being sure how region object lifetime was managed since unlike other GDI objects there wasn't any function to delete it).
> most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output
Do you know if there's a way to access info documentation in a PDF reader (or failing that a browser)? I often try to read the info pages then quickly give up because I don't want to fuss with the navigation. I would love to be able to say `info --format=pdf --open-with=evince sed`. Is anything like that possible?
EDIT: Another cool approach that would preserve hyperlinks would be a command that starts a local web server on say 4400 and launches firefox on its index.html.
AFAIK GNOME and KDE's help systems have the ability to view info files and there is also the tkinfo viewer i mentioned.
However note that the "source documentation system" i refer to is texinfo, not info. Texinfo is a preprocessor and documentation language (think docbook) for manuals that produces a bunch of formats, one of them being info, a text-only hypertext format (which was one of the earliest hypertext formats AFAICT). GNU info is a viewer for that format, but there are others, however all of them just view info files and have its inherent limitations (e.g. preformatted text, links using a rigid syntax, etc) - though also they have benefits such as support for topic keywords, indices, etc.
Texinfo can also be converted to other formats like PDF (through tex - i guess the initial version generated only tex and info output, thus the name texinfo) and HTML. So you wont be using texinfo to view info as PDF files, but you'd be using it to generate PDF (via tex).
I guess the "texinfo" and "info" names can be confusing and make people think that they are the same thing - the fact that AFAIK texinfo is the only info file generator (and that GNU info is called just "info" which is the same as the file format name) doesn't help :-P.
As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, controls, etc) and for each group there is an "overview" section (e.g. Windows introduces the windows concept), then a reference (often split in several parts itself) and finally one or two examples (though that was optional).
The help itself didn't have "howtos" or "rationales" but those were available through MSDN (later at least) as knowledge base articles.
(modern winapi documentation is a mess on that regard, especially if you do not already have a vague knowledge of what you are looking for, because even though it is largely the same text, they have split and moved things around too much and put irrelevant distracting links everywhere)
On the Unix world, the original X11 documentation follows a similar pattern, though for other more recent projects there is usually a very one-sided approach: as the article says, most projects only provide API references and perhaps a single (often unfinished) tutorial.
GNU projects usually have documentation in texinfo which is laid out as a book and is often very good (most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output nor really the info format itself that has more usable viewers like tkinfo). It also has a similar approach as the Win3.1/95 docs, though i think the lines between "guide" and "reference" are often blurred. This largely depends on the project though (e.g. the glibc manual has these better divided, whereas the bash manual tends to be more "blurry"). Also i'm not fan of GNU's style of function references - i prefer the more common/manpage-like style where for each function/macro/struct/etc you have an isolated page a very brief description about its purpose, its declaration, a list of what each parameter (for functions and macros) does, its return value (if any), a detailed description (if necessary), any requirements (e.g. headers, for APIs with multiple headers) and links to other relevant functions and guides.
Also i find examples for each function to be nice though this is even more rare than guides.
As a sidenote, i loathe autogenerated documentation and "docgen comments" in source code (and not only because they tend to enforce the "reference-only" approach). I think those should be totally separate and not pollute the code with documentation (especially headers as that makes it harder to read the headers that also act as a quick overview for an API).
Though having a tool to automatically check docs and sources for mismatches (missing functions and/or functions with wrong declarations in the docs) is helpful. But i'm not aware of anything that does that.