The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?
4 Answers
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.
answered Mar 21, 2019 at 16:45
I would say an API needs reasonable examples of use, and needs attention paid (or links provided) to other closely related elements of the API; even if it is just like "See xyyGraphInit".
You want your programmers to be able to use the product quickly and without having to read the whole dang thing five times. I can (and have had to) read through a list of a hundred routines in an API, and finish that task with hardly a clue of what to do first, or how to get what I wanted.
IMO that is a badly documented API. The API is supposed to help me (the applications programmer) get to the useful things in your product, if your API just explains individual routines and doesn't make it obvious how to make your product actually do work for me, then the documentation is bad.
Most APIs that I have used require several calls to set up and get something done, and many such combinations to accomplish such tasks; for example there may be a hundred types of interactive graphs it can produce.
Other technical writing doesn't necessarily have all these interacting parts and subsets of options and everything else. Code is special in that way, and documentation should provide some guidance on not just the individual routines, but how they are related to each other and how to use them together.
First of all, let’s make it clear, what API means. API stands for Application Programming Interface. API is a set of tools, communication protocols, and subroutine definitions for building software. Generally speaking, API is a kind of communication channel that allows two separate programs to communicate. How does it work? API is also a part of your daily life. For example, you need to turn on your TV from a distance. You press the ON/OFF button on remote control and the TV turns on. This is how API works. Radio/infrared waves through which a remote control communicates with a TV set act as an API in this case. APIs can be divided into three groups:
- Software API
- SCPI (Hardware API)
- WebAPI
Technical writers develop documentation that includes instructions about how to effectively use a hardware (SCPIs), web-API, or software API. Usually, API documentation contains all the information required to work with the API; it also contains details about classes, functions, arguments, and the like, supported by examples and tutorials. API documentation is usually created by means of regular tools and editors.
More information why this documentation matters is here: What is API Documentation
-
“API is a kind of communication channel that allows two separate programs to communicate.” Not necessarily. Every library has an API, but the library and the using code are part of the same program. Indeed, that's the original use of the term API; the interfaces between different programs were formerly just called protocols. The language changed in that respect, but I think it is important that an API does not imply several programs. It just implies several software components.– celtschkCommented Aug 19, 2019 at 10:28
In one sense you could say, Nothing. All technical writing should be clear, give good examples, etc.
The main thing that comes to my mind is that for an API, you pretty much have to have the bulk of the document be reference. That is, you have to list all the API calls, give all their parameters, etc.
It would be a really good idea, by the way, if you actually explained what each call does and what all the parameters are and what they're for. I've read several API docs that just list function names and parameter names and data types and that's it.
