Thursday, October 20, 2011

Top 10 Components of an API Doc

In order of importance:
  1. Sample code
  2. Complete reference, including expected behavior, argument ranges, default values, possible side effects, and related methods
  3. Error handling information
  4. Developer's guide
  5. Changelog or release notes
  6. Installation and configuration information
  7. Tutorial or codelab
  8. Conceptual overview
  9. FAQ
  10. Usage info for related developer tools
What do you think, folks?  What'd I miss?   What do you think is out of order?
Posted by at
Labels:

4 comments:

  1. Jean-Philippe CottinOctober 21, 2011 at 10:23 AM

    I don't think you missed any important component. However I would say that "the flow of the document" is also important. I read an API doc like a story (ok, maybe it's just me) so it's very important for me to :
    - have right away an high level overview
    - understand where to find the tool(s) [installation]
    - get a progressive sample code

    This would get my feet wet. And then the doc would

    - enter in the details "chapter per chapter"
    - get the complete reference and the FAQ somewhere in the doc,
    -...

    So I'm not questioning your proposed ranking of the component's importance, but I'd like to see a linear doc where I could have this quick-start.

    ReplyDelete
  2. UnknownOctober 21, 2011 at 4:32 PM

    Good point, JP. The flow is very important! Your suggestions are great.

    ReplyDelete
  3. Eric GApril 2, 2012 at 11:00 AM

    If anyone has shining examples of error handling documentation, I'm looking for them! Please share a link if you have one.

    ReplyDelete
  4. UnknownApril 2, 2012 at 12:48 PM

    I don't have a link, but I have some suggestions. IMHO error handling guidance is a shining example of the kind of doc that should be collaborative. People using different environments encounter different errors, and need to resolve them differently. So the more you can enable people to help each other, the better.

    At the very least, you should troll the internet, and especially StackOverflow, for guidance on what errors users are encountering, and how they're resolving them, and make sure you include that guidance in the doc. If you can swing it, you should also make the error handling doc into a Wiki and/or stream in relevant posts from StackOverflow so that people can help each other resolve errors.

    ReplyDelete

Subscribe to: Post Comments (Atom)