API Documentation Mistakes and How to Avoid Them

Treat API documentation as User Interface for developers who will develop and extend your application/product beyond your imagination. Good API documentation is first step of making your API popular.

Mistake #1: Developer doubles up as documentation writer
The Mistake and Misconception
Developer, the creator knows about the system the best, so she can write the best documentation. More over API documentation is targeted to developers’; they understand each other’s lingo and mindset.
The Truth
Certainly developer the creator knows the best but most of the time her sight is myopic due to limited understanding of whole system. Moreover developers are not got in natural language due to their engineering background (no offence to engineers and developers. I am a proud engineer and developer). And lastly, developers are too near to system. What is obvious to them may not be so simple and straight forward to a greenhorn or outsider.
The Solution
Get a good technical writer.

Mistake #2.: A typical technical writer writes the documentation
The Mistake and Misconception
A typical technical writer is good at writing about user interface which targets non technical users. API documentation writer should be skilled to explain from developers’ perspective.
The Truth
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 Solution
Get a technical writer who can code (certainly not on regular basis) or at least have done coding in past.

Mistake #3: Focusing on How and forgetting Why
The Mistake and Misconception
Most of the documentation put emphasis on How to use an API but ignore Why.
The Truth
Sometime this avoidance is purposefully but most of time this is due to lack of attention. Just remember that if documentation does not answer Why, they may end up using API in wrong way and API may become unpopular among developer community.
The Solution
With How, answer Why as well and explain under what scenario what to use, How, and Why.

Mistake #4: Not providing enough help for Getting Started
The Mistake, Misconception, and Truth
In most of API documentation, certain level of maturity of developer is assumed but never stated. This lead to lot of confusion and un-popularity of API..
The Solution
Provide multiple levels of documentation. One targeted to newbie and one at advanced developers. Also state the assumptions very clearly.
Provide simple tutorials and sample codes. Strive for sample applications which use the best practices of API.

Mistake #5: Sketchy sample code
The Mistake, Misconception and Truth
For a technical writer it is very tempting to be descriptive about API.
The Solution
Certainly descriptive text is important and helpful but just remembers that developers like to learn by doing not only by reading. Pair up Technical Writer and developer if needed to develop sample code and sample applications.
Sample code should consider:
1. Relevant information should be grouped together
2. Clarity is more important than efficiency
3. Simplicity is one of the most important factor
4. Completeness of code
5. Avoid unnecessary details ( for example use hardcoded values instead of parametrization)
6. Comment the code
7. Use sensible nomenclature