How to get the best API document?

The most important piece of UX for a product isn't its homepage or the sign up process or the SDK download. Well! It is the API documentation.

No one understands the effectiveness of a product unless its usability is well explained. While most developers are dreaded by the thought of writing a document, it is the technical writer, who has to take up the task of creating meaningful and explanatory API documentation.

Having created API documentation for some time now, I bring to you some useful information that may help you create better ones.

Be sure of who your audience is
It is very important to understand who is going to use your API document. You may be writing for a new developer who is looking to get started or someone who is debugging a specific issue or even a researcher figuring out the various possibilities with the APIs. Once you have identified your audience, the same should be conveyed in the Intended Audience section of your API document.

Build you content around these essentials
The  API document must describe each API ,detailing its functionality with mention of the data types and function specs.  Content for each API must start with a brief description of “What the API does?” followed by the individual API calls that can be made under it. Each of the calls must be explained individually with details about the Request Parameter, Response, Exceptions, Samples, and Error Codes. The “How to use the API?” part of every API must be elaborated minutely.  Do not forget to script the error codes or messages from a client’s perspective; include all those scenarios that are out of control of that API.

Describe each API separately
 As this document mostly deals with developers, try not to include any big abstractions. Add more and more real examples to reduce the time taken by the developers to understand the product.

Minimize the number of clicks
Navigating to the appropriate page must be quick especially in this case as the content is expected to spread across different pages. It is therefore advisable to keep related topics under one page. If the content of an API is not enormous, you can probably use the all-docs-as-single-page approach recommended by Parse.

Use plain English
An  important point to be conveyed in this case is that, although the audience of the API document are the developers, not everyone may be familiar with the API domain and the associated jargon. Therefore it is recommended to explain each API call in simple English.  If domain-specific words and jargon are being used for the first time in a particular section, you can probably link them to useful definitions.

Use multiple languages
List examples in multiple languages that your API supports, most likely via client libraries. Learning a new API is hard enough without having to parse unfamiliar languages. The developers get a huge advantage when they receive a pre-built and tested project in their choice of language of that is already using the API.  The sample codes are reflection of the client’s foundation and hence gives the developers the best possible path to experience the best usability of the APIs.

Integration with the Support team
In case you have a support help desk to redress all concerns about the APIs, it is a good practice to provide a persistent entry point into that support system from your API document. With users  being able to post their query inline with the documentation, helps improve the quality of the documentation right away.