Posted 48 months ago on 12/12/2009 and updated 4/9/2010
Good API documentation can have a tremendous impact on whether a software platform is adopted. However, too often API documentation ends up being confusing and hard to follow, which results in developers choosing another way to accomplish their goals. This article describes five common mistakes that are made in creating API documentation and describes solutions to avoiding those mistakes. Following good API documentation practices can provide developers with the content that they need to be able to take full advantage of a software platform's capabilities.
If your product is a software platform, then your Application Programming Interface (API) and its documentation are your user interface. Just like a user interface on a software application, if your documentation is confusing and not enjoyable to use, then your user has a bad experience. Software developers give up easily and find other ways to solve their problems if they cannot understand how to use a software platform.
This article describes the five biggest mistakes you can make when creating API documentation. Avoiding these mistakes will allow you to create documentation that inspires developers to use your platform to create great applications.
Mistake #1. Having Your Developers Write the Documentation
It might seem logical to have the developer who created an API be the person to write the documentation. After all, who knows it better than the creator? Also, you won't need to take someone new and bring them up to speed.
Typically, this is the worst mistake you can make. In general, developers dislike writing, and will resent having to do this task. Many developers simply cannot write well -- it's a talent that's very different than writing code. And lastly, your developers are simply too close to the material. What's obvious to them is not going to be obvious to someone who is new to what they have created. They often lack the ability to step back and see their work with fresh eyes.
What you need is a technical writer who is good at learning the material and then writing about it.
Mistake #2. Having a Typical Technical Writer Write the Documentation
There are a lot of good technical writers out there. A typical technical writer has experience explaining how to use a software application from an end-user's point of view. They are skilled at describing menus, dialogs, and work flows. But explaining how to use applications is very different from explaining how to develop software.
Sometimes you will find technical writers who have dabbled in programming. This is a big improvement to working with those who haven't, because they will at least have an understanding of the concepts of programming.But what they won't have is an understanding of how a commercial software developer thinks. How do developers get started learning something new? How do they use prototyping and architectural design? How do they debug their code?
The ideal writer has spent time working as a professional developer. These types of writers are sometimes referred to as "Programmer/Writers". They understand the pain that developers go through in trying to get a software platform to work, and how good documentation can make their development go better. These writers could be developers if they wanted to, but they often choose to be programmer/writers because they find they enjoy the challenge of finding the right words to describe the highly technical task of computer programming and they enjoy frequently learning new technology. They will require a higher hourly rate than a typical technical writer; however, you will find that they not only do the job better, but they can often do the job a lot faster, thereby costing you less in the end.
Mistake #3. Focusing on How and Forgetting Why
Suppose you have a technical writer with a good background in software development. You'll probably find that your writer loves to write about how to use your technology, but if you are not careful, you may forget to have them explain why it should be used. For developers to learn a new platform it requires a large time investment, and if they do not understand what benefits they will be getting, they will skim the documentation, and move on to another way to accomplish what they are trying to do.
The first few paragraphs of the technology overview need to lay out why the software platform is important. The overview needs to immediately list the advantages of the software platform, ideally contrasting it to existing approaches. It needs to give clear examples of when you would use the technology. Ideally these are real-world scenarios. (See the article Using Real World Scenarios in Conceptual Documentation.)
Google has recently released a new programming language, Go. Google has done a number of things well in documenting this new language and its APIs, but there are a few important aspects that they missed. Their website (http://golang.org/) has a home page that lists the advantages of Go has over existing languages. They nicely lay out six important features, and for each of them, they give some examples that back up their claims. It's done in a way where developers can quickly skim the page and get an idea of what Google is attempting to accomplish with this new language.
However, they are missing a piece of crucial information: who uses Go? Other than the title, which refers to it as a "systems programming language", there is very little information that would help a developer understand if this language would solve his or her problem. "Systems", after all, could refer to server systems, middleware, or even desktop or mobile operating systems.It would be useful to have some case studies that showed where Google itself is using the language and what specific advantages it gave them.
Mistake #4. Not Providing Enough Help for Getting Started
Once developers have determined that your platform is likely to be useful to them, then the first thing they will want to know is how to get started. But if you ask your own developers what they feel most needs to be documented about the APIs that they have created, they are likely to mention some advanced features that they know are hard to comprehend.
The people who create an SDK have worked so closely with it that they forget how hard the very first steps are. Yet, this is a critical part of the adoption of an SDK. In 2009, SDK Bridge put out a survey on what people want to see in API documentation, and one of the most common threads running through the responses was that developers wanted help in getting started.(See the article Survey on SDK Documentation.) If developers find it hard to get started, they will give up quickly, and find another way to accomplish their goals.
A good way to get developers started is through tutorials and sample code. These approaches are often much more effective than the same information in the form of descriptive text and architectural diagrams. More on sample code in the next section.
Mistake #5. Skimping on Sample Code
Sample code can take a lot of work to get right, and it is sometimes tempting to include minimal samples and focus instead on descriptive text. However, another common thread in the responses to the Survey on SDK Documentation was the importance of good sample code. Developers often learn a new platform by starting with code that they know already works, and then modifying it or adding to it. Most developers find it easier to learn by doing than by reading.
You need to provide good sample code that demonstrates what your APIs can do in a way that is meaningful to the developer. There are a number of ways that good sample code resembles good production code, such as plentiful comments, well-named variables, etc. However, there are a number of ways that good sample code is different than good production code. For a full discussion, see Guidelines for Good Sample Code.
In this article, we outlined the five biggest API documentation mistakes. To avoid them, follow these three guidelines:
1. Have your writer be someone who understands how software developers think and can write effectively for a software developer audience.
2.Make sure your documentation covers why your APIs should be used, and not just how.
3. Give your developers plenty of material that allows them to get started in an easy, hands-on fashion, including tutorials and sample code.
Providing documentation that is understandable and well written is a critical part of developers adopting your platform.
Great article. I think this is your best yet. I like it because it pretty wide appeal and everyone likes list articles. Easy to digest. I featured this article, along with Bryan's Geo-location article, in this month's emag (Jan 2010) which means all will see it.
Peter, the article is very good and is very well organized in terms of the information flow and grammatical usage. The information in this article is very well helpful for programmer writers and technical writers responsible for producing API documentation.
I have been working with a large scale SOA based software platform wherein we produce end user online documentation and api documentation to our customers. Along with those points mentioned in your article, the next mistake that a writer should not do is listed below.
# Unorganized way of providing API documentation structure
Usually the API documentation consists of classes, interfaces, methods, data types, code snippets, etc. While providing the API documentation, it is important to plan or determine the organization of your API documentation. If it is not well organized, then your customer or developer or the testing team member will not be able to fetch the information in the API documentation properly.
To do this, firstly plan accordingly with respect to the software platform used. Write some usability cases how you want to plan the organization of your information. Discuss this organization of api documentation information with your peers and with the managers and also with the support group including your customers.
Services/components of your software platform can be listed as different links that would further contain the links of classes/methods/data types. Alternatively, this information can also be organized based on the software platform's perspective. I.e from the developer's point of view. These efforts depends on you as a technical writer to understand your audience background or know-how. If you feel that the developers are very well comfortable and are more experienced with the software platform, then you may look at better ways of organizing your api documentation.
Note: This is a one time effort that you need to plan carefully. If your plan is not done correctly, then your customers or developers may not be happy even though you might have written very good api documentation.
The api documentation that is being discussed here is with respect to documentation delivered online.
Excellent point, Ramesh. Organization is critical. Not being able to find the information they need is a common source of frustration for developers.
I am in the process of gathering information about the differences between Web APIs and more traditional APIs, and how this influences how documentation should be written. (By traditional APIs, I mean those where the call and the processing are done by the same CPU. The best term I've heard for this so far is "local APIs".) One of the key areas is documentation organization. Local APIs can be naturally organized according to the classes and their members. However, with Web APIs, it's common to have a piece of functionality exposed in several different ways, such as HTTP, SOAP, REST, etc. Some of these may be organized to look like object oriented calls, and others are not. So your documentation needs to be organized by functionality, rather than by classes and methods.
Another interesting point is that Web APIs should be technology-agnostic, so you may need sample code in several languages, such as PHP, Java, Perl, etc. Ideally, your organization makes it easy for a developer looking on how to use a particular technology can find that information easily.
Just a comment on your mentioning multiple languages in documentation. I have been looking at some documentation that shows things using the language I use. But it also shows it in another language that I will never use. I wish these language example documentation systems gave the user the choice of what language to see rather than having to constantly scroll down through or hiding the language not of interest. At best, the extra language is distracting. At worst, I don't noticed that I have scrolled into the other language and get misled or at least confused by what I see...
You offer a few good ideas in this article, but you might be missing some important truths in your #1. Remember that the programmer of the API routines *is* the first documenter of that functionality. Why? That person chose a programming language in which to implement the API interfaces. That person also probably named all the routines (subject to some naming convention scheme) that implement those interfaces as well as named all the parameters whose features and purposes the writer must document for users. This also means that the writer should look over the API designer's shoulder and ensure that the naming conventions visible in the API interfaces make sense and are sufficiently self-documenting.
You also don't mention how useful it can be to draw a few pictures (diagrams) that illustrate to a new API user what's going on when the user's code utilizes the API's interfaces.
Also, producing coding samples that use a given API routine aren't worth much unless they include the *context* of the call--that is, what additional API calls are required *before* and *after* a given API routine is called.
I do think you need to make a distinction between API design and API documentation. You're right that the writer should really be involved in the design process, but the reality is that just doesn't happen very often in industry. The writer is typically brought in at the tail end of the process.
Diagrams -- yes, they can be useful. They just didn't make it into the top five.
Context is important, too. I believe you could see that best through good sample code.