As a technical writer, you may have asked the question of how to move from writing about end-user or GUI-based products to successfully writing API documentation. While good technical writers already possess the skills and best practices needed as a foundation for writing API documentation, there are still several important challenges and requirements to address. Here are five often-asked questions about writing API documentation:
1. What are the differences between writing API documentation and other types of technical documentation?
Although API documentation adheres to many of the accepted writing principles and guidelines, there are some key differences. The standard or baseline for API documentation is a complete, accurate reference manual. “Complete” means that every component in the API, method/function/resource, error message, and other components are documented. (The terms, method/function/resource are functionally equivalent. In this article, the term "method" is used to generically refer to all three terms.)
One key difference is that in many cases, sentence fragments are acceptable and desirable. For example, a method is usually explained by one or two sentences that describe what the method does. These sentences do not need to be complete sentences. They can be fragments. For example, a sentence explaining an openFile method might read, “Opens a file for read/write access by default.” However, technical writers new to API documentation might write, “The openFile method opens a file for read/write access by default.”, where the added phrase “The openFile method” is unnecessary. Keep in mind that the primary audiences of APIs are software developers. They tend to be very direct, factual, and interested in what the software does, not in any marketing hype about how well, fast, easy to use some tool is to use, and so on.
2. What tools do I need to learn?
Although you can use any of the common technical writing software that you use for other technical writing to produce API documentation, there are tools especially appropriate for API documentation. These tools are used to write specially formatted comments in the source code files that are then extracted by the tool and formatted into API reference documentation. Some of these tools are used as standalone tools; others are part of the same coding development tools that software developers use to code APIs. A common standalone tool used in API documentation is Doxygen. In addition, a common tool that is part of a common development coding tool, the Java Development Kit, is Javadoc, used primarily to create an online reference system for Java APIs.
Learning how to use source code control tools is also recommended. These are tools used by software developers that store incremental versions of the software source code in a repository and easily tracks the changes between successive versions of a source code file.
3. Do I need to be a programmer to succeed at writing API documentation?
You do not need to be a professional programmer to succeed at API documentation. But you do need to be able to read code to some extent. C or Java are the most useful programming languages to learn. You should be to recognize and code the common elements in a programming language such as methods, the parameters that can be specified for a method, the value returned by a method, and how to code error messages for common mistakes, and call those error messages when such a mistake occurs. Luckily, there is a wide variety of resources to help you get a basic understanding of programming, ranging from books, college courses, and online learning sites.
4. How do I break into API documentation?
A best practice is to study examples of good API documentation to get a feel for how API information is presented. The following are several examples of best examples to study:
Another way to is to take an existing API and modify or make improvements to it. This gives you a real-life sample that you can show to prospective hiring managers. Suggested examples are the help for the Microsoft Help Compiler or Oracle’s Java Messenger Service (JMS), both of which are available for free. You might also contact openstack.org and volunteer to write API documentation for an open source project.
5. Why should I consider writing API documentation?
Writing API documentation is a great way to enhance your skill set and better position yourself in the technical communication industry. In addition to working with developers, writing API documentation can lead to exposure to sophisticated tools such as development integrated development environments (IDEs), the same development tools used by developers. Other useful tools are “smart” text editors that are much more powerful than Notepad. These tools provide color highlighting for the syntax used in common programming languages to make it easier to distinguish code from documentation comments, have the ability to auto-backup open files, and other handy features. Another type of tool you may run across is a differencing tool, which compares two versions of a file or directory and visually displays the differences between them. Most source code control tools have a basic differencing tool built-in, but there are some excellent standalone differencing tools that can be integrated into your source code control tool or used in conjunction with your source code control tool. As you gain experience and fluency with development and authoring tools, you increase your value to your current organization and your marketability.
Summary
To review the five takeaways for technical writers new to API documentation:
- API documentation should be very factual and terse. Sentence fragments are acceptable.
- Learn tools that scan specially-formatted comments in the code and generate your documentation from those comments. You also should become fluent with source code controls, which are used extensively by API developers.
- You do not need to be a programmer to succeed at writing API documentation but you do need to be able to recognize basic programming elements such as methods, their parameters and datatypes for the parameters, their return values, and the error messages returned by a method.
- If you are new to API documentation, study examples of API documentation to get a feel of the writing style.
- Writers producing API documentation are exposed to a variety of development and authoring tools, increasing their value and skillset in the technical communication industry.
Looking for additional tips on how to write and develop clear API documentation? Read our white paper, The Definitive Guide to Creating API Documentation.
