In a perfect world, API documentation would contain clear, complete instructions on everything that developers need to know to use your platform. In reality, organizations have limited time and budget to create API documentation, and so organizations need to prioritize to create documentation that is most useful to the people who will use it.

SDK Bridge set out to find out what is most important to the people who use APIs by sending out a survey and asking them. We found, not surprisingly, that many thought that documentation could be better. When asked to rate quantitatively, people rated overviews, sample code, and API references the highest, followed closely by tutorials. When asked for open-ended comments, a large percentage mentioned working sample code as helpful, and an equally high percentage mentioned how important it is that documentation be complete and accurate. Two other important factors that were mentioned by several respondants are (1) it is very helpful to explain why you would use something in addition to how you use it and (2) completeness and accuracy are critical.

Crowd-sourcing (that is, using Web-based technology to gather API documentation content from your users) has the potential to lower documentation costs and make your documentation more relevant. However, relying solely your developer community to provide documentation will result in uneven quality and coverage. I recommend a hybrid approach, where professional programmer/writers write parts of the documentation, as well as rewrite and polish content from the community. Several tools are available that enable communities to contribute documentation content. 

The number of Web APIs is growing rapidly, especially with the increasing popularity of Software as a Service. Because Web APIs are still fairly new, the quality and format of their documentation varies a great deal. Good documentation is important for Web APIs because experimentation is more difficult than with local APIs. Because Web APIs are language-neutral, you may need to write sample code in a variety of different languages. Be sure to cover authentication, error handling, and HTTP information.

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. 

A survey was sent to software developers and other software professionals to ask what was important in SDK documentation and where they would like to see improvement. The results indicated that the current state of typical SDK documentation is "Fair", which was the middle choice of five ("Excellent" to "Unusable"). The answers to multiple choice questions indicated that overviews, API references, sample code, and tutorials were all considered high importance, whereas blogs and forums were considered less important. When asked to write what they considered important, sample code was mentioned in 61% of the responses and overviews were mentioned in 30% of the responses. Also mentioned as important were help getting started, explanations of why something should be used, accuracy of information, and the ability to find information easily.