Sample code or small example apps. Although sample code was not rated significantly higher than other types of content in the multiple-choice part of the survey, it was mentioned by 61% of the respondents in their written comments. It was referred to as "the most helpful thing". Respondents wanted runnable examples that illustrate something, not just "Hello World" and talked about the desire for real world examples. There was a desire for very basic samples that would lead to more complex ones.
Help with getting started. Several respondents mentioned the difficulty of getting started with a new platform. One said, "People who make SDK documentation often don't think like a beginner who is just getting started with their SDK." Another requested "help with learning curve," and another suggested "going all the way down to the bottom (installation and setup of tools)". Another commented, "Once you've got the basics, it's easy to begin poking around on your own. But if you can't get started, that's frustrating."
Explanation of why. Eight of the respondents mentioned that it was important to understand why the software platform or individual APIs should be used. One summarized this as "Why, why, why, not what, what, what." Another cautioned that this should be from a programmer's point of view, and not the marketing department. Case studies and real-world examples were desired.
Accuracy is critical. Respondents wanted "absolute mathematical precision" and "no ambiguity". One respondent said that "the most unhelpful thing in SDK documentation is incorrect information," and another said, "Sometimes misinformation is worse than no information at all." This suggests how valuable technical reviews are; unfortunately, technical writers often find that getting developers' time for reviews is very difficult.
Ability to find information easily. This theme came up in several ways. Heavy-cross referencing and indexing was mentioned, as well as improving search capabilities. The ability to come at the information in different ways (by topic, alphabetically, etc.) was also mentioned.
Good overviews. 30% of the respondents mentioned overviews. Respondents desired "a high level overview of the concepts that bridges into the detailed API documentation" and said that it was "missing from many API documentations."
Content should be written by someone other than the developer. Two developers brought up this issue. One said it was not useful when documentation "is written by the same person that wrote the API. To them, everything makes perfect sense and requires little description." Another said, "Developers should only be the Subject Matter Experts, not the authors."
Flow diagram. When explaining tough concepts, a good flow diagram goes a long way and wins developers hearts.
Web APIs. Authentication is often required for Web APIs, and this needs to be documented in detail as well. If developers need API keys, be sure to give them step-by-step instructions on how to obtain these. Also, don’t forget that Web APIs are built on top of HTTP, which is an incredibly rich protocol. You may have HTTP-related information that requires documentation, such as caching, content type and status codes.
In conclusion, sample code, overviews, and help getting people started should be given the highest priority. Content needs to explain why something should be used in addition to how it is used. Also, because accuracy is considered critical for documentation users, managers need to be sure that the developers who created the APIs are available for discussions with the writers and for technical reviews.
In the end, the best formula for effective SDK documentation is the combination of good writers who know how to write for a developer audience and developers who are willing to take the time to work with them.
1 comment:
Just pointing out that you had a typo in your title. "Dcoumentation"
Post a Comment