Post History

Source: https://writers.stackexchange.com/a/43875
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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](https://docs.oracle.com/en/java/javase/12/docs/api/index.html) for the Java API, and here is a [reference page for a single class](https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/io/ByteArrayInputStream.html).

**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](https://docs.oracle.com/en/java/javase/12/), 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](https://developer.android.com/docs) 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](https://developer.android.com/samples/) is a link to a GitHub repository containing an [introduction](https://github.com/googlesamples/android-JobScheduler/#readme) 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.

Original score: 7