The target user base for the problem described below is one of the most neglected and underrated one - Programmers/Developers/Coders.
Consider, for example, this java doc which is explaining about various details about an API by the book (as per convention).
What it does
It tells me that
- what this API can do
- Purpose of he API
- various methods in this API
What it doesn't do
However, there are plenty of other blogs, articles and posts (many of them in this very Q&A site) which will talk about information not given here
- Pros and Cons of this API
- When to use it
- When not to use it
- With which other API(s) this API is most recommended
- With which other API(s) this API is least recommended or recommended not to use it
- play around with the API (if possible)
It becomes a problem because
All this information missing from here makes this documentation
Boring to read and hence designed as only a reference. And hence very little time is given/allocated to maintain and update the same.
Gives an opportunity to many other experts/experienced people to make their own best-practices list which may or may not stand the test of time, and may not get peer or community reviewed thoroughly.
Developers need to bookmark tons of links and trust some of them, sometimes prematurely.
However, SOME might argue that API docs are suppose to be that way and convention doesn't allow more information to be shown there.
So my question is - Should an API documentation include all these information or am I simply over-thinking this and these docs are just the way they should be?