Creating Great API Documentation: Tools and Techniques

Question

I'm tasked with creating a web service that will be used by several different developers using different platforms, working for different companies, and having greatly varying skill levels. As such, I would like to create documentation for this web service API that is both complete, and very easy to understand. Although I'm sure this is a noble goal that all documentation projects attempt to achieve, I have not found the best set of tools and/or workflows to help my project get there.

What tools and techniques do you find most useful in creating great API documentation?

Do you find auto-generating documentation tools sufficient to provide end users with all the information they need to use your services?

Do you find Wiki-based tools easy and fast enough to maintain up-to-date documentation of your API?

Have you found any tools or techniques that provide the "best of both worlds" - automation as well as flexibility? Do any tools exist that simplify the process of documentation multiple versions of an API?

Answer 1

A few weeks ago I proposed A Standard for Open Source Code Documentation which gives some loose guidelines for documenting open source code. Jacob Kaplan-Moss has also written a series of articles on the subject. In short, I believe that most APIs can be well documented with the following sections:

1. What it is and why you might want to use it
2. How to download/purchase, install, and configure it
3. How to get started with it (a tutorial)
4. How to do more advanced things with it (topical guides)
5. API documentation (auto-generated)

These sections may not be published in the same place (they may be on separate web sites), or created with the same tools (wiki, auto-doc generator, etc), but every section should be directly accessible through links from every other section (there should be a table of contents at the top of each source). This allows you to use the most appropriate tool for each section of the documentation and still address all the relevant areas.

I think a multi-tool approach like this is necessary because:

• auto-generated docs keep up with the latest API but are useless to beginners
• wikis get the community involved but can't keep up with frequent API changes
• README files are too static

Again, as long as each section is accessible from each other section, I think using multiple tools/sites is the best way to document most of the time.

Answer 2

I've done my Ph.D. on API documentation in Java. Web services are obviously different, but I believe that some findings are global.

First, you have to accept the fact that you will have two "classes" of readers. One small class would be the people who do the complete read-through for every function. As with Java, you do want your API doc per each "function" to be perfectly specified. You don't want your users (or internet forums) to guess. Unfortunately, this class is fairly small, and often occurs with mission critical clients or with organized code reviews.

The more common form of API documentation user is the "I just want to get things done" type of person. He (or she) has a notion of what they want to accomplish. They also have an idea of where to find it, so let's say that they've found your function. Here is where the problem starts - they don't really want to read the documentation. Now suppose that your call has five parameters, four obvious but one has a caveat (e.g., "send only an open session"). If you go through the list of parameters and fully specify each, they'll get fatigued and skim and not notice the critical thing. I can't stress this enough - people will completely not notice something that stares them in the face. This gets even trickier - if they believe that they fully understand the function, even if they do bother to read the documentation, they will skim it. I have seen people missing obvious caveats on methods with two-sentence documentation.

So here is what you can do:

1. Assume that most users will not actually read the documentation of the functions they call. In fact, the more intuitive your API is, the less chances are someone would read the documentation. Everyone would read a function with a strange name and 20 parameters. But if you write a really straightforward API with a nasty caveat, you run the risk of it never being read. the only solution here (I have some for Java, but not for the web) is to avoid surprises.

2. When you do write your full and complete API, explicitly highlight the nontrivial bits (I can show you a whole taxonomy of what is surprising in Java, a lot translates). Better yet, have three people look at the documentation and pick up the things that are not intuitive. If you can't factor them out of the API, highlight them.

Finally (and the credit here is to Jeff Stylos who also did his Ph.D. on APIs): Provide recipes for certain operations (even as a separate web page), and consider creating "placeholders" in the documentation text for methods that are not part of the API but users would concievably want. For example, if many users would want to do Z, but the way to do it in your API is to do X and then Y, add to the documentation a "do Z" placeholder, and tell them specifically to call X and Y.

Answer 3

There are a lot of utilities that allow you to write and maintain a complete and updated API documentation. Of course you can find them easily by a simple search (doxygen, javadoc, rdoc, etc.) However, as Uri pointed out above, people just need concise and to the point to be using a package or API.

Thinking in what to write, and how to write it, it came to my mind the most useful help I remember having obtained. Most perl module documentation have a "SYNOPSIS" part. It is a real starter with the library or API that I haven't found surprisingly, say, in automatically-generated API documentation (for instance that of Qt or some javadoc-generated Java packages). Take into account what you find when you say:

$ perldoc CGI

You know what to expect, and you find an example just to the point:

     # CGI script that creates a fill-out form
     # and echoes back its values.

     use CGI qw/:standard/;
     print header,
           start_html('A Simple Example'),
           h1('A Simple Example'),
           start_form,
           "What's your name? ",textfield('name'),p,
           "What's the combination?", p,
           checkbox_group(-name=>'words',
                          -values=>['eenie','meenie','minie','moe'],
                          -defaults=>['eenie','minie']), p,
           "What's your favorite color? ",
           popup_menu(-name=>'color',
                      -values=>['red','green','blue','chartreuse']),p,
           submit,
           end_form,
           hr;

      if (param()) {
          my $name      = param('name');
          my $keywords  = join ', ',param('words');
          my $color     = param('color');
          print "Your name is",em(escapeHTML($name)),p,
                "The keywords are: ",em(escapeHTML($keywords)),p,
                "Your favorite color is ",em(escapeHTML($color)),
                hr;
      }

      print end_html;

Of course, after that you have a complete API documentation, caveats, exceptions, rules, tips, etc., but for me, this piece of information has more value than the API documentation itself. As you are needing more functionality of the package, you of course read the documentation, or even when you see that the example code does something that you need slightly different, you know what API bit (function, method, etc.) you have to look to see the possible variations.

Answer 4

As for the tools, all the companies I worked with used their own tools (a combination of their own tools with some third-party ones) to build docs. I guess it means that a really good generic tool either does not exist or is very hard to find.

As for the techinique... The one that works really well for me is the following:

1. Make every developer write doc comments. Create some kind of auto-generated docs with each build. Set up the build so that missing doc comments become errors.
2. Hire professional technical writers to create readable documentation out of those auto-generated docs. A really good writer will identify the classes and methods that are most likely to be used by your customers. Since writers are not directly involved in creating the API itself, they often come up with more understandable examples than developers.
3. Set up some kind of reflection system that will notify writers about changes in the API. So, if you add/delete/change a method, the writer can be notified about that.
4. Examples, examples, examples. People love examples. Find a way on how you can provide examples whenever possible, from simple to advanced ones.
5. Give some way to your readers to provide comments on the docs. You don't necessarily need a wiki, but be sure that you can get and incorporate feedback. Also, let people know that you do change the docs by their requests, it increases the amount of useful feedback.

Hope, this helps.

Answer 5

Summary: Use a compiler to generate API stubs from the documentation itself.
Caveat: Not a cheap solution, but who said you can get a free lunch nowadays.
Hints: Use flex/bison to generate a API stub generation compiler.

You are on track if you want a way to document your API well. There are countless APIs with bad documentation which force the user to either go to source directly (a rare user that one), or simply give up and find alternatives.

A big problem with writing documentation for the APIs is that they become out of sync with the implementation over time. E.g. a developer modifying an API to accept an extra argument, may not remember to update the documentation for the function. So, even though the documentation for the new API gets generated, it may get out of sync with the actual implementation.

We solved this problem in our company by generating API stubs from the documentation itself i.e. the documentation specifies the API interface. Docs are described in the syntax understood by a stub generation compiler. The compiler ensures that each argument is documented and there's a comment describing the API, and generates a stub file as well as formatted documentation. The stubs are filled in by the developer.

E.g. perf.api

#########################################################################
@arg1(string): Blah blah blah
@arg2(string): Blah blah blah
@perfcounter: Provides a cli interface to get back performance counter.
@return(int): perf counter value
#########################################################################

Compile:

> stubcc perf.api
  generated perf.h
  generated perf.c

Generated perf.c file:

#include "perf.h"
int
perfcounter_stub(char *arg1, char *arg2)
{
    return perfcounter(arg1, arg2);
}

Generated perf.h file:

#ifndef PERF_H
#define PERF_H

extern int perfcounter(char*, char*);

#endif

The developer implements perfcounter() in a separate file.

This ensures that the API documentation is always up-to-date and documentation is enforced by a compiler. Of course, you can still badly document the API if you want, but you'll never end up forgetting to document something. To ensure doc quality, we have a separate group of people who review the quality of the documentation (work with the developers to understand what they are trying to document, and suggest improvements/corrections etc.)

Answer 6

Self-explanatory naming in whatever elements of the API are exposed.

Clear and concise documentation of these elements.

The documentation should not be generated as a consequence of the API design, but based on the functional requirements specified at the project's initiation.

The tool is irrelevant as long as the documentation is updated.

Answer 7

A few things to consider:

Whatever route you take, make sure when you release version x.y of the software, you can also release a versioned x.y of the documentation. Most wiki based approaches just track the head and quickly become useless to anyone stuck working with an old version of your API (ok maybe this is less of a problem if you're a webservice and just going to force all users to upgrade). You want to encourage people to submit bugs against the documentation (and the documentation will contain errors) just as readily as they'll submit them for the software itself, and track those edits in your BTS/version control just like you would a software bug. Again, a problem with wiki documentation seems to be that even if you empower end-users to edit it, they don't feel qualified... and noone submits bugs against wiki documentation either, so errors don't get fixed.

Provide illustrative, working code samples (and test the code samples as part of your build-and-test system). Most devs will initially be far more interested in those than function-by-function API descriptions, and many will never look any further if the samples are good.

If you host documentation online, use web analytics tools to see what people are reading. Put effort into the stuff people are finding useful.

Answer 8

Agreeing with the sentiments of several previous posters, many users will not read the documentation. In my experiences, there are three methods of documentation that, when used together, make a very powerful and useful tool.

Layer 1: Self-Documenting Code As much as possible, make your API require as little documentation as possible. Follow (and publish) naming conventions for your functions, parameter, and data types that make their purpose obvious. The best documentation is the documentation that isn't needed.

Layer 2: Walkthroughs / Sample Code While many people won't read through API documentation, reading through sample code is generally considered to be less painful (and to some, more helpful). Create some simple, straightforward examples that use your API and publish them separately from your API docs. Cover as many of the common usage scenarios as possible. While this won't give users the same degree of knowledge as learning the API, it will at least give many users a starting point. Even if they simply cut-and-paste sample code and use it as a skeleton for their own, they will be starting with known working code and you will reduce the number of 'beginner' questions and support requests that you receive.

Layer 3: Detailed, Always-Updated Documentation Whether very many people read it or not, it is always important to have a detailed, comprehensive set of documentation available. For doing this, I prefer using document generators such as Doxygen. This works especially best if you have some sort of automated build process. For our project, we have a server that does nightly builds and also re-generates the project documentation nightly. That way, everybody can see the most up-to-date docs when they view them on the web.

Document generators give several advantages. First, it is easy to keep your documentation up-to-date at all times. Since the generators use comments and notation within the source code to create their output, using document generators also encourages developers to thoroughly and appropriately document their code (that way the documentation is in the source and in external docs, and you only have to write it once). If your project contains several branches or you have developers working on several different versions of your code, a document generator can create documentation for whatever particular version of the source code that is being used. Also, auto-generated documentation does not require any extra effort to back up or archive (since it can be re-created from the source code which you are keeping in a version control repository, right?).

In my experiences, providing these three layers of documentation yields the best results. Those who want to read docs and learn the API can do so, and those who do not can get by fairly well without doing so. From your point of view, this method also requires minimal efforts. The first layer is something that many software projects do already. The second layer typically comes in the form of copying sections of code you have already written, simplifying it, and posting it to a website or wiki. The third layer might require some work to re-format existing comments to follow the conventions expected by your documentation generator; however, Doxygen (and probably others) can generate a fairly decent set of docs even without adding any Doxygen-format comments.

Answer 9

A couple documentation techniques I've learned the hard way:

• Syntax diagrams (especially railroad diagrams) provide a very clear, readable way to describe the syntax of commands and options.
• Always provide at least one example for each function/concept you use. Preferably, include a simple use and a complex one.
• Use the Inverted Pyramid writing style -- provide the most important information first, then progressively less important! This lets your user choose how far to read based on the detail they need. Applies to overall documentation too -- give concepts in the first section, and save the precise details until the end.
• Tutorials or samples are essential, and should be neither trivial nor overly complex!
• Do NOT force your users to learn your own system of brackets, braces, angle brackets, and bold/italic/underlining/spacing in order to read your documentation. Yes, you should have a consistent system, but it should follow one of the common conventions, or preferably use syntax diagrams where possible.

Answer 10

What tools and techniques do you find most useful in creating great API documentation?

I haven't created any great API documentation, but I've used some.

The most valuable tool and technique I've encountered is for the documentation to include complete examples that are simple, that actually work, and that users can interact with. One of the most brilliant API documents I've ever read is the Inform 7 Designers' Manual, which seems to have split into two manuals since I last read it. An early draft (2006) was about 700 pages long and contained well over 300 complete workable examples, each of which could instantly be loaded and interacted with. This was an astonishing aid to learning a very rich, complex API.

Another technique I've found very helpful as a learner is something Don Knuth does consistently with his documentation: he includes exercises, and the answer to every exercise is in the back of the book.

Answer 11

Do you find auto-generating documentation tools sufficient to provide end users with all the information they need to use your services?

No, typically a lot of detail is missing from the code comments used by these tools. See below.

Do you find Wiki-based tools easy and fast enough to maintain up-to-date documentation of your API?

No, someone must produce the documentation, usually a coder. Coders are not always proficient at writing documentation, which a wiki format requires. See below. Also, a Wiki would not meat your requirement for "[documenting] multiple versions of the API"

Have you found any tools or techniques that provide the "best of both worlds" - automation as well as flexibility?

XML Templates

Do any tools exist that simplify the process of documentation multiple versions of an API?

Source Control Management. Darcs or Git amongst several others.

What tools and techniques do you find most useful in creating great API documentation?

Simply put: make your API documentation itself be code.

The biggest mistake most people make is to ask coders to write documentation... Its like asking a documentation writer to code. It isn't necessarily that one or the other hates it (although that may very well be the case), but rather they aren't proficient at it. It isn't their core competency. So regardless of what tools or best methods you might have, you're going to get low quality output because a coder isn't an expert in writing documentation.

However, a coder is the best suited for documenting an API. Thus, you must make documenting the API a function of coding. Now most people get this far and say, great, lets use code comments and auto generate our API documentation from those comments. No good. Now you can not treat API documentation as a deliverable. It is integrated into the code itself, and you can not revise it without touching the code base. Coders will see the code next to the comments, and think the code self obvious and minimize (perhaps subconsciously) the comment/documentation detail, not addressing various caveats that aren't self apparent unless you're looking at the code itself. Amongst many other reasons, those are a few to avoid that path.

So, the mindset that needs to be had is formed from such:

• Treat the API Documentation as a code project
• Coders should be able to access the API documentation 'code' and make revisions as easily as if they were coding. This means it must be in a plain text file that can be edited in their favorite editor/development environment.
• Coders are used to syntax correctness and the confines of a compiler/language. Therefore use a template system that requires and enforces specific content areas. Basic XML is a start.
• Keep the translation scripts (XML to whatever) as part of the API documentation project, and encourage the coders to improve upon those scripts... ie give them something to play with. (optional, but actually helps produce better documentation in the long run)
• Each API feature should be documented in its own source file. Do not put more than one documentation unit into a single file. This keeps the focus simple and clear for the coder to avoid getting bogged down in "documentation".
• Set tasks, milestones etc just like a normal project. Do not make the API documentation wholly contained within your main project that you're documenting. This helps give validity and focus to the output and helps avoid it being side lined or minimized - oh, we only need a day to write the documentation cough. Very much a mindset issue, however it can be an effective approach.

One implementation I have found to work well is to use XSL Transformations taking XML templates and CSS inputs to produce XHTML output. Very simple to see the results and easy to tweak. This is also easy for a designer to produce a pleasing layout/look for the documentation without having to touch the documentation itself.

Taking that approach and mindset, we can now version control our documentation, revise it, release updates and have developers work on it and treat it just like any other coding project. Bugs can be submitted against the project and releases. etc etc. If you use a good source control tool, then maintaining documentation for various versions of the API is a breeze.

Answer 12

I think that if you are in control of creating the API, it is better to start with usability in mind (designing a usable API - I'm speaking about Psychology of programming field of research here, not gratuitous opinions) instead of be concerned with usability merely in documenting it. I.e. API usability is strictly related to API documentation usability, but are not exactly the same - at least this is my impression from experience and some reading on the subject.

Uri Dekel's (also here) detailed answer in this thread is very interesting and I hope its (and Jeff Stylos) dissertation will be available soon somewhere on the web.

In the meantime, have a look at The API Usability project @ CMU, particularly at the Usability of eSOA APIs subproject (bottom of the same page). There are a couple of papers that corroborate my hypothesis that API usability and documentation usability are different concerns:

• A Case Study of API Redesign for Improved Usability;
• Improving Documentation for eSOA APIs Through User Studies.

So better you give attention to both.

There also this site devoted to API Usability: it has a Resources section with a bibliography.

CodeProject has an article on API Usability that seems well informed and written.

Tom Johnson, a senior technical writer, has a blog post specifically about Documentation Usability.

And so on.. a simple web search with "API usability" and "web services" gives much more material from which to choose.

P.S.: choosing an appropriate tool for documentation is, IMO, the last of your preoccupations.

Answer 13

I'm currently using Sandcastle Help File Builder.

This is a tool for Windows, which can generate MSDN-style documentation from the XML documentation comments which you embed in your .NET source code.

This auto-generated content is good, but not enough: you also need introductory sections, which introduce the software as a whole, say how to install it, perhaps have tutorials for various use cases, etc. You can use SHFB to author this kind of information too: SHFB calls it "Conceptual Content", and you write it /mark it up using the 'MAML' schema.

From within the conceptual content which you write, you can easily code hyperlinks to any page of the API reference documentation.

Also, although the content of the conceptual content is up to you, it's rendered to HTML using the same style-sheets as the API reference: for example if a page of the API reference documentation (generated from comments in the code) looks like this, and page of conceptual content (written using MAML) looks like this.

The tool also generates a table of contents, to help navigation. I've mostly found MSDN documentation sufficient; so maybe a toolset which can generate MSDN-like documentation is sufficient too.

Answer 14

Documentation generators are great to create links between parts of the documentation and check for layout and such but they can't add information that isn't there. The most often missing piece of information is: "Why would I want that?"

In my case, I use two tools:

1. A Wiki to give you the big picture. What's going on where and where to look for details. This stuff rarely changes and just tells about design decisions and gives pointers. It's easily editable but mostly static.

2. Lots of tests which show how you can use the code. You need to write them anyway, so write them just like any other code (clean and readable) and turn them into your examples. Main advantages: Documentation can lie, be wrong or be outdated. Tests Always Tell The Truth (TATTT).

And always remember: Just like a line of code, a line of text must be maintained. Worse, a line of text doesn't come with a compiler to check it. So keep the documentation as short as possible (but not shorter).

Answer 15

An intial point is that if you overcomplicate the documentation process then you and subsequent contributors are less likely to use it. If there's a learning curve to documenting your project, you've already put a barrier in the way of communicating with your target audience. Maintaining the documentation process can itself become a time consuming project.

As has been pointed out, there are different audiences and it's appropriate to address each with separate documents, produced with separate tools. As a bare minimum you need two documents:

1. The 'View from 10,000 Feet" document that explains the structure, features and process that your API supports. The point of this is to give context to any more detailed documentation. Few users actually want to read all of your wise words, so when they come along with a question 'How do I do X', you need to let them know 'Look at component Y' so they can cut to the chase. The context document is most effective if you can generate a few diagrams to make the core structure(s) something that people can visualise. There are loads of options, but a Wiki provides a means to host any such document in a way that the users can contribute and let you know what areas they feel need expanding on.

2. The low level document that details each call, response, parameter and datatype. The best feature of such documentation is to ensure that it is comprehensively cross-linked and up to date. When I look at a given call, I want to be able to reference every data type, every related call and any other details of the API with just a mouse click. To my mind, auto generated documentation from comments in code is an ideal mechanism to provide this because:

   • Cross referencing is managed automatically, is always comprehensive and up to date
   • The documentation can be (re)generated from the source code and in sync with new releases at will
   • As the documentation sits next to the code itself, it can be easily validated by a combination of automatic code style checkers and code reviewers.

It's true that keeping such documentation up to date requires discipline, but it minimises the effort required to do so (when you change the code, the documentation is right there and easily editable) and maximises the return on simple text comments.

One of the reasons Java became successful so quickly was the consistent and intuitive documentation of the core classes through Javadoc.

If your API is an ongoing project, using collaborative tools such as a Wiki, forum or mailing list to document the API allows you to engage your end users and understand where they need your support. Hopefully it'll be so popular that users themselves will start offering support and building a community that goes beyond your efforts to document the project.