The Diátaxis framework [1] provides a nice suggestion of different types of documentation, and when to use them. None of these types
is "best", each serves a different purpose.
replies(3):
> Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective
I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself:
> Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.
Examples are crucial to documentation, but they aren't — at least in this view — a kind of documentation, so much as a technique for documenting.
Not sure who came up with it first, but your link is similar to the author's link at the conclusion of the article:
> Since even major software projects rarely offer [4 distinct kinds of documentation][1], I am often hesitant to click on a "Documentation" link
Personally, I prefer documentation written as an explanation. If I understand how the thing works or why it's done that way, everything else is easy. Examples/tutorials/how-to guides only help me develop a conceptual framework by experiencing it, and I know that's how some people learn, but a skilled technical writer or educator can help me generate that conceptual framework correctly the first time.
I think the reason API references are so common is that they're really best suited for someone trying to build a wrapper or fully-compatible alternative implementation...which is what the original authors were doing, before the project existed. Many projects started as an internal, private API reference, and generating documentation can be as easy as making that public.