By Cyrus R. Kirby
There are two sides to technology that a content developer supports. The side that most people are familiar with is an application’s interface. Often referred to as the “GUI” (Graphical User Interface), a great deal of time and effort is taken to ensure the interface is easy to use and looks sharp. The side that most people do not see, but that is exceedingly important to programmers, is the API reference documentation. An API (Application Programming Interface) describes how software components should interact with each other through data structures, routines, variables, and object classes—essentially, the gears that make the GUI work.
Two Very Different Deliverables, Two Very Different Audiences
The differences in the documentation process for GUIs and APIs are not subtle. When documenting for a GUI, most of the content is task-based and describes the landscape of the GUI. GUI documentation highlights visual elements without going into detail about what’s driving the function. Individuals who look at GUI information want to know how to navigate what is in front of them, use the GUI to the fullest, and get on with their day. A content developer’s chief concern is clearly communicating and demonstrating how the GUI works.
The goal of API reference documentation is to detail how all the gears fit together, spin, and interact to make the GUI work. Details about packages and classes, field and method summaries, and code examples are just some of the information included. Individuals reading API reference documentation want to know what is being called to in the code, why, and any limitations that might exist. Using the API reference documentation, a programmer can provide additional functions and features that might be visible in the GUI or stay unnoticed below the covers. A content developer’s chief concern is reducing any ambiguous language within the API reference documentation to ensure the information is clearly understood.
Specific Information for Specific Users
An API is nothing but code when it is first created. Any individual who has taken programming courses will tell you how important it is to structure the code correctly and to make comments in the code about what’s going on. This is necessary for two reasons. First, to document the logical thinking that explains why code is written the way it is. Second, to quickly describe how the code works to anyone who is looking at it for the first time.
API reference documentation exists because of the need to be able to describe what the code is doing without having to read the code directly. Well-structured and documented code is great for an individual looking directly at it, but understanding one class doesn’t give the programmer the “big picture.”
GUI documentation is focused on task-based information. API documentation is purely reference. A great deal of explanation is sometimes needed to describe what a variable is reserved for, how routines are called, and dependencies on other object classes. Most of the time, an individual can document the reference information directly within the code and use a third-party software application to create API documentation. This means the content developer is working within the same code as the programmers and needs to know what they are doing. Content developers cannot add text wherever they think it is appropriate. They need to follow guidelines and standards, but more importantly, not damage the code.
Same Job, Different Focus
This brings up another important difference between writing for GUIs versus APIs. Content developers can familiarize themselves with a GUI fairly easily without needing to know anything about what makes it work. To write good API reference documentation, the content developer must be able to read and understand code. The content developer must also be able to work well with programmers and use the same tools in which the code is being written and maintained. For content developers not familiar with the development process, development tools, or the code in which the API is written, creating API reference documentation is going to be a struggle, if not impossible.
It’s important to note that a content developer who is writing API reference documentation need not be an actual programmer. It would certainly help, but it is far from necessary. A content developer need only be eager to learn, feel comfortable asking questions, and not be afraid to stretch his or her own technical skills.
Writing API reference documentation is no different than writing for a GUI if we consider that all content developers research and familiarize themselves with the subject matter before they document it. While a content developer for a GUI will focus all their time and energy on the end-to-end user experience, a content developer for an API will focus on making certain that every aspect of the API is clearly defined.
API Formatting Options
Formatting of API reference documentation is oftentimes fairly minimal. If you’re writing the API reference documentation for print or online documentation (like a PDF), then the formatting will include your standard headers and tables. If you are writing for online use, for example a website, then the same format is used, but there is additional work to build the website and provide cross-reference linking.
Most API documentation is created using software that formats the code, doing the heavy lifting of creating the finished product for the content developer. However, there are some cases where the content developer will need to write the API reference documentation from scratch. Most of the time, this is because the code is not formatted well enough to allow for an automatic document to be built, or only a few APIs need to be documented. If such is the case, then a quick discussion with the programmer is necessary to establish an agreed upon format.
A great example of API reference documentation is the Java™ Platform, Standard Edition 7 API Specification website (http://docs.oracle.com/javase/7/docs/api/). The entire website was created using Javadoc, a software tool that looks at code and formats it into HTML-based API reference documentation. It is important to note that Javadoc did nothing more than compile and format the content. A content developer or a programmer wrote the reference documentation in the code and made sure the code was properly structured. Javadoc looked through the code, formatted it, and produced a website you can navigate.
Take advantage of any opportunity to write or contribute to an API reference document. It is an excellent way to learn a great deal about a software product and the process used to create it.
Cyrus R. Kirby is a project manager, information architect, content strategist, and content developer with over 13 years of experience. His educational background includes English education, computer science, and communications. Cyrus has written technical documentation for both proprietary and open source projects, finding it difficult to determine which he enjoys more. When not focused on the digital world, he writes about parenting and his board gaming hobby at fathergeek.com.
