Developers need to work with third party code to develop complete applications. In order to integrate the applications with third party code programmers need well written API documentation. API stands for Application Programming Interface. API Documents are also required to work on platforms (and develop applications) such as Intuit, Sun, Google and Salesforce.com.
API documentation requires writing about programming code. It’s an advantage to have a technical background to write API documents. Since it is difficult for the companies to find writers with technical background, non-technical writers are writing API documents. Technical writers, with non-technical background, find the word ‘API Documentation’ a bit too technical, and generally cause anxiety in them. My aim is to help reduce some of this anxiety by making them more aware of what ‘API documentation is all about.
API Documentation – Software Development Kit (SDK) and Programmer’s Documentation
Before we start talking about the API documentation, let’s see the bigger picture first, wherein the requirement for a developer to work with the company’s code requires more than API documentation. Programmers may need:
Programmer’s documentation describes all or some of above mentioned points. Organizations include all of these in SDK (Software Development Kit).
Types of Programmer’s Documentation
Programmer’s documentation may have some or all of the following:
Here we are focusing on the first point. API reference documentation and also be referred as API documentation, and these terms will be interchangeably used.
Overview of API documentation
API documentation is the most commonly used programmer’s documentation. It is basically a reference documents which describes:
API documentation includes information about the code. It gives details about the APIs (also called methods and functions) that developers use to connect or interface with the software application. API documentation can be done for all sorts of software technologies such as Java, JavaScript, C++/C#, TCP/IP, AJAX, JSP tag libraries, and XML schemas.
Key areas to be considered when writing API document are:
Source for Creating API Documentation
Information for API documentation comes from one of the following source:
Standard groups Writers often start out with the raw content provided by the programmers.
Typical Outline of an API Document
Most of the information in the API reference documents is targeted towards the APIs themselves. There is nothing like a “standalone outline” – but an API document will consist of the following:
How to Document each Function in an API Document
The exact content may differ for each document, but following should be included for each function:
Example of an API Document
The following example shows how a typical function is documented. More than 80 percent content of an API document will look similar to what you see below.
ArrayBI→ collect()
Description
collect() calls a test function for each element in the array. All elements for which the function returns a non-zero value are collected in a new array which is returned.
Syntax
ArrayBI ArrayBI→ collect( AlFunction testFunc, … );
Returns
An array containing those elements for which testFunc returned a non-zero value.
Arguments
testFunc:
A function that should accept only one item from the array as its first argument. A value of non-zero is returned if the item is collected; a value of zero if the item is not collected. Additional arguments can be supplied and are passed to the test function after an ArrayBI item. The test function should be prepared to accept these additional arguments.
Example
Continuing from the example for accumulate(), the following code returns all the odd values in arr:
arr->collect( func(x) {
return (x%2) != 0; } ); // Returns (5 9)
See Also
API Documentation Tools
API documents can be extremely long and repetitive. But API Documentation tools can really prove to be helpful. Developers insert comments to the application during development process. The API Documentation tools then parse or break down the code for inserted comments to make API documents. This works better when programmers and writers agree upon the type of comments to be inserted. Some popular API documentation tools include:
Although the tools help generate quickly, but can only work if there is good discipline of writing good comments in agreed upon formats. This may also need special training of the programmers who generally shy away from writing comments.
Common delivery formats for API Documents
Once the documentation is complete it is delivered as a PDF or as online help or both. The idea is to deliver it in a printable format.
The concentration is more on online help as organizations are moving towards SaaS (Software as a Service) model. Help can be generated in any style or format, depending on the software help, e.g. WebHelp, HtmlHelp and JavaHelp etc. WebHelp is gaining popularity as organizations are making web-based delivery models.
Conclusion
Although API documentation is a bit technical in nature, with patience, even technical writers with non-technical background can also start writing these API documents.
