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 tools 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:

  1. API documentation should be very factual and terse. Sentence fragments are acceptable.
  2. 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.
  3. 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.
  4. If you are new to API documentation, study examples of API documentation to get a feel of the writing style.
  5. Writers producing API documentation are exposed to a variety of development and authoring tools, increasing their value and skillset in the technical communication industry.

About The Author

Ed Marshall

About Ed Marshall

Ed Marshall is an independent consultant technical writer and the sole proprietor of Marshall Documentation Consulting, with over 28 years of experience. He specializes in technical documentation for developers, including APIs (application programming interfaces), SDKs (software developer’s kits), Web Services products, etc. Over his career, he has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching and replacing text. He has given many presentations at local STC chapters and Summits, the WritersUA conferences, Information Development World, the TEKOM trade show in Germany (October 2012) at the organization’s invitation, and many other events. He is a Certified MadCap Advanced Developer (MAD) for MadCap Flare. His web site is www.MarshallDocumentationServices.com. He can be reached at ed.marshall@verizon.net, on LinkedIn, and on Twitter @EdMarshall.

Last Modified: June 26, 2017

This entry was posted in Tips & Tricks and tagged . Bookmark the permalink.

Comments

  • Riley VanDyke October 6, 2016 at 9:58 AM

    As a happy user of Flare, one of the problems I encounter is that the auto-generated reference material described in the article (“These tools are used to write specially formatted comments in the source code files…”) is how best to integrate that reference material with concept and task material created in Flare.

    So far the best I’ve been able to do is *circumvent*, rather than truly solve, the problem by creating a folder in a Flare project, copying the reference material (which is typically similar to a tri-pane online help system) into that folder, then hyperlinking from the concept and task material to the body of reference material. I configure the hyperlinks to open that reference material in a new browser tab or window.

    With that in mind, I, and other Flare users I’ve corresponded with, would be very interested in more elegant approaches to the problem of integrating auto-generated API reference material into a Flare project.

    • Ed Marshall Edward Marshall October 6, 2016 at 2:10 PM

      Currently, Madcap Flare does not have the capability to automatically import specially formatted comments from source code for APIs and generate API reference documentation from those comments. If this capability is of interest to you, submit a feature request using the following link: http://www.madcapsoftware.com/feedback/featurerequest.aspx

    • Marjorie Jones October 14, 2016 at 8:29 AM

      I have successfully auto-generated content from developer code and included it in Flare-generated documentation in the past. In my case, it was report model descriptions, which were defined in XML files in the code base, but the same method should be able to be used for API functions. I needed a bit of developer help and a bit of scripting to set it up, but it wasn’t hard.

      I created a Flare topic with the layout and styles and I wanted to use, and placeholder content. I then asked the developers to write me something that extracted the information from the report model XML into the format shown in my example topic. I then wrote a script that ran this once for each report model file in the codebase. This generated the topics, which can be added dynamically to your TOC with a bit more scripting.

      The really nice touch was that the developers didn’t hard-code the layout of the Flare template I gave them. They made that a parameter file with placeholder content. So if I wanted to make any changes to the format of the output, for example to add another section heading or change the style used for some element, I simply made the change in the template file. The only changes that need developer expertise were changes to the actual number of fields that were pulled into the Flare topic.

      This was all I needed, as all the content in each topic was either common text, or came directly from the XML descriptions of the report models. But you could easily auto-generate Flare topics that include common text, text from the specific API definition, and additional descriptive text generated by a tech author. You could put the latter into a snippet using an agreed naming convention, and include the snippet in the auto-generated topic. Then when the API spec changes and the topic needs to be regenerated, the extra descriptive text is still included in the updated topic with no rework.

Have Something to Say?

Your email address will not be published. Required fields are marked *