Should an API documentation include When-to-use and when-not-to-use list?

Question

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?

Answer 1

I definitely agree that documentation should contain the extra information that you suggest, but at the same time that is hard to get right, boring to do and takes effort.

John Resig (creator of jQuery), in an interview about Building jQuery at 4:19 into the interview, talks about how his documentation with examples of jQuery was one of the best early decisions he made.

Slightly later on, (this is my paraphrasing of what he says):

"When you're trying to manage a good project, especially open source, code is only a very small proportion of the total equation. You have to spend a lot of time and a lot of effort in making something that people are going to want to learn, that it's easy for them to learn and once they do learn it they don't get frustrated later and leave"

jQuery documentation is probably one of the best examples you'll find.

PHP is often derided as a programming language - but the documentation is excellent. The user contributed (with voting) is also an excellent addition to it - which often adds some of your extra requirements such as 'when not to use it'.

Answer 2

Yes, having all of this information directly in the documentation is quite useful. Good documentation gives you all of the information you need to understand the API, interface, or other tool--and this is something which goes beyond a simple technical description of how it works.

There are examples of documentation that does this.

One that I am familiar with is the Perl documentation. The documentation for modules is analagous to your javadoc example, but it often contains information like:

• Why you would find a particular module useful.
• Recommendations for alternative approaches.
• Warnings about potential pitfalls.

And so on. As a result, it teaches the developer not just how to call a function/method but when and how to use a module.

Or, check out this introduction to the API for Trello (an online tool for managing tasks), which gives you key information for getting started, not just a reference to the interface. They also give you an online sandbox to actually try it out.

Yes, it is possible to do it better than that javadoc example.

Answer 3

I have used a few APIs and went through the documentation. Developers usually do not refer to the API documentation to make judgement about whether they should use it or not/ where does this API stand with respect to others etc. The API documentation is used only when you know you are going to give it a try. It's treated like a piece of document that's supposed to familiarize you with the subtleties of this particular API and it's classes and methods as quickly as possible. There is usually a 'use' section which shows you how to you use it in your piece of code.

I like the brevity of API documentation. That said, I would love to see some interactive documentation which let's me 'play' with the API. I think this part would help me explore the API and it's possible potential. The other thing that comes to mind- the reason that we may not have this by now is APIs tend to be cross platform, hence building a web based cross platform interface to explore is piece of work in itself.

Answer 4

Answering my own question to address a few points since no one else has addressed them fully.

Yes, the API documentation should have these details. These details are absolutely critical in many scenarios including the survival of the language sometimes. Also, there are some downsides to them as well.

Why it should be there

Easier learning curve

While it is true that developers will first go to a Getting Started tutorial or a Hello World program first. But this phase does ends at some point when

• Either you need to dig deeper into the requirements,
• or Checkout more options available to do the same task,
• or Try and find a built in API to do a task rather than re-invent a wheel.

If the API documentation doesn't have

Lack of easier learning This alone can ensure

Easy to make a new/better API discoverable

Some alternatives may be available in the API documentation (not marked as alternatives, just discovered after browsing the API doc) but one has to

• Either test those API themselves,
• or Search for a documentation or tutorial on internet and rely on whatever wisdom is available online,
• or Rely on the ongoing wisdom/best-practices in their organization.

Once something become a best-practice, very rarely it is documented that

• How it became a best-practice - meaning what all tests were performed,
• For which all scenarios this best-practice is valid,
• and finally When this best-practice is not valid.

NOW, if the API makers create a new API, developers usually won't look beyond this best-practice artifact, unless the language or the API itself promotes the culture of going through API doc when you decide to upgrade the libraries.

Easy to tag Do's and Don'ts scenarios

When you have Do's and Don'ts of using an API in the API documentation itself, it is easy to tag the page with it as well, which means it is easy to search and group the APIs based of certain requirement as well.

For example, if I search for

XYZ API for transaction management in XA Environment

or

APIs to avoid when working in container based connection pooling

I should get the list of APIs that I need and the ones I should avoid. This not only helps the API users (developers) but also in turn can be hugely helped by the community of the API users as well leading to quicker adoption.

Only Downside?

Only downside of having such effort put into the documentation is that because API makers will have to do a lot of impact analysis before releasing a version leading to much slower release cycles and also leading to less responsiveness to the community of API users.