6

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?

  • 1
    Yes it definitely should - but it's hard and time consuming. – icc97 Jan 31 '16 at 11:58
4
+50

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'.

  • 1
    Thanks, totally agree that jquery's API documentation is much better. Proof of the pudding lies in the fact that they didn't have to make another developer manual (at least not called it that way). It is true that it boring and hard to get right, but I think it is worth the effort since this good documentation leads to lesser learning curve and quicker adoption. This probably is the reason why jquery is adopted and has in fact replaced many other libraries like Mootools, Prototype and YUI. – gurvinder372 Feb 1 '16 at 5:30
  • I agree examples are an excellent way to help someone learn, but that’s not the same as the author’s expectation of should/shouldn’t instructions, pros/cons, and what 3rd party APIs are "best" to use in conjunction. – jlmakes Feb 8 '16 at 15:07
  • @jlmakes indeed examples aren't. You can push the documentation further, but the further you go the harder it gets to maintain. I think the PHP route where the pros/cons etc. are added by users is the best route to go. – icc97 Feb 8 '16 at 16:32
  • I agree, leveraging the community for these more subjective requests is perfect. I don’t think the onus should be on the API developer to create it, but rather to support it. – jlmakes Feb 8 '16 at 16:39
4

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:

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.

  • Thanks for useful links. but I think perl API doc is also giving very limited info perldoc.perl.org/functions/abs.html . Trello however is better. – gurvinder372 Jan 29 '16 at 5:53
  • 1
    @gurvinder372, well not much documentation is needed for an absolute value function! Check out something more complicated. For example: perldoc.perl.org/DB_File.html This includes extensive examples, tips and tricks, common questions, etc. – user31143 Jan 29 '16 at 6:37
  • @gurvinder372 to be fair to perl docs, abs is a fairly trivial function, you could be more critical of the next link down perldoc.perl.org/functions/accept.html, so clearly it's not perfect. However it is very good and much better than java. The next link down is perldoc.perl.org/functions/alarm.html which does contain the extra examples and is more typical of what is in the doc – icc97 Jan 31 '16 at 11:56
1

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.

  • 2
    Developers don't use this documentation to make that judgement today because that information is not available here. They need to rely on other links to do that. Which is precisely the problem I feel, since no one can tell the pros and cons of an API then the makers of the API themselves. – gurvinder372 Jan 29 '16 at 5:13
  • What you are saying is not completely correct. The java example you showed is a not a good representative. For example, check out documentation for this library for iOS github.com/BradLarson/GPUImage. The description does not have a section of pros and cons but the description does give you a comparative analysis of the potential with respect to contemporary solutions. A good developer would always write about it, if not insist on it in the documentation. – ypag Jan 29 '16 at 17:38
  • Docs in the link you have shared may give more info, but it is not very easy to go through since it is not very structured. Also its decision to show comparison with contemporary solution is purely to sell the API to developer before he makes a decision to use it, not after. Once he has chosen to use this package, there is very little on this page to help user with. Also, we can't compare a package (GPUImage) with a technology (Java) – gurvinder372 Jan 29 '16 at 18:11
  • "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." Strong disagreement with this statement. Far too often the API documentation is the only way I can find out whether I should be using an API or how it compares to others, precisely because the other documentation (if it even exists) fails to address those questions. – Daniel Beck Feb 2 '16 at 19:06
  • I think what i meant was I would not solely rely on 'pros and cons' section(assuming there is one) in the documentation to judge if I should use the API or not. There are far too many APIs out there for any task and I do not expect one API documentation to give me an updated, informed, and balanced survey with respect to others. – ypag Feb 3 '16 at 21:02
0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.