Four kinds of documentation

Four kinds of documentation
divio.com

"Explanation - Topic" sounds a bit wonky as a section/title. Does anyone have a suggestion what to call those types of articles?

Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the project does not work and I should be very sceptical - I am sure there are projects that do it better, but for me no-content auto-generated documentation is a real code smell.

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.