: Re: What is special in API documentation compared to general technical writing? The title says it all: what is special in Application Programming Interface documentation compared to general technical

@Turnbaugh521

Vote Up Vote Down

API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to someone who's trying to accomplish some task, and while some of those people (and tasks) are deeply technical, API documentation has some special considerations:

API reference documentation is essential. Sometimes this is the only documentation you get; sometimes it's accompanied by other doc which I'll get to. For each element (class, REST call, etc), API reference documentation presents the syntax, parameters/arguments/options, return values, restrictions, error conditions, inheritance relationships (if applicable), and a (usually concise) description of what it does. Good API reference documentation includes overviews (for example at the class and package level) as entry points ("how do I use all this stuff together?") and good, focused examples.

API reference documentation is usually generated from comments in the source code, using tools like Javadoc, Doxygen, and Sphinx and following a standard format. For example, here is the top-level page for the Java API, and here is a reference page for a single class.

API documentation includes other elements. Too often it doesn't, but (to continue our Java example), if you go to the top-level page for the Java doc set, you'll see overviews, tutorials, tools, and more. Oracle labels only the reference documentation I described in the previous paragraph as "API documentation", but the Android developer documentation takes a more integrated approach that leads with "build your first app" (tutorial) and "sample code".

Examples are important, and I don't just mean "here's some code". In the Android doc, each entry on the examples page is a link to a GitHub repository containing an introduction that lists requirements, describes the example, and tells the reader where to get help. (It's accompanied by the actual source code.) Example code needs to be clean and well-commented, but it also needs to be presented in a context.

(0)

Login to post a comment!