Documentation for Software Engineers

Writing technical documentation for software engineers is more than authoring code comments. In order to use an application programming interface (API) or existing source code effectively, software engineers require different types of information. For this reason, technical writers who author API documentation need to analyze the requirements of their target group.

About the Target Group

There are different types of readers – this also holds true for software engineers. To find out more about the way your target group works and uses documentation, you can develop personas. Personas are commonly used in user-centric software design and in user interface design.

Based on experiences from several API documentation projects, we developed three basic personas to represent software engineers. You may use these as templates. However, specific personas should be developed for your application and development scenario.

API documentation needs to comprise more than code comments. In order to support the different needs of the target group members, the following document and information types should be provided:

• Programmer's Guide or Programmer's Cookbook, containing conceptual information about the product and the API architecture, descriptions of programming tasks (recipes), and programming examples. Especially important for George and Nic.
• Reference information, such as extracted code comments, describing the individual API objects (classes, interfaces, methods, operations, etc.). Especially important for Samantha.
• Sample programs, which may be provided with the product deliverable. Especially important for Samantha and Nic.
• Product documentation, describing the business processes provided by the API.

Programmer's Cookbook

The Programmer's Guide or Programmer's Cookbook covers the following main topics:

• Programming environment
• Architecture of the API
• General programming tasks. Examples: Event handling, transaction handling, resource handling (for example, memory), error messages, localization.
• Recipes for specific tasks that describe how to achieve goals in API programming. The recipes may be based on user stories/use cases from product development or based on typical customization tasks. Examples of recipes are "How to authenticate a user" or "How to add a document to the repository". Recipes must provide links to the reference documentation, extensive (and working!) sample code, and links to sample programs.

The technical writer functions as author and coordinator of the Programmer's Cookbook. Code samples may be written by technical writers with programming skills or by software engineers of the development team. The technical writer can effectively use his/her knowledge from the product documentation regarding user stories and may collect additional user stories from the company's software engineers. Based on their structural and language know-how, technical writers are best suited for creating the structure for cookbooks and monitoring the use of terminology.

Reference Information

Reference information for APIs contain details about the functions and parameters of the individual API elements, such as interfaces, methods, constants, or operations. Reference information is often authored as code comments and published as HTML by means of tools like Javadoc or Doxygen. Integrated development environments (IDEs), such as Eclipse, make code comments for imported classes easily available. However, for some API types, such as Web Services, other formats may be necessary, because the services provided via the API are described in an XML file. For such application scenarios, a wiki can be used to author and publish reference information.

Reference information may contain short code samples. Adding large code samples to code comments is often not feasible, because layout instructions mostly need to be given in HTML notation.

The role that technical writers play in authoring code comments largely depends on their technical level – whether they have programming skills or whether they focus on authoring skills. Technical writers having little to no programming skills may, however, review code comments with regard to terminology, language use, and structure.

Product Documentation

The product documentation is usually the place for information regarding the business processes and architecture of the product. Also, general technical concepts, such as user management or server/client communication, are explained here. This general conceptual information is, of course, also useful for software engineers who develop based on the product's API. When a software product provides an API, the product documentation must contain a short description of the API and references to the Programmer's Guide.

Collaboration and Feedback Functions

In addition to these document types, software engineers require collaboration functions, such as developer networks or social networking functions, which enable them to share information and to exchange experience with other developers who are using the same API. Also, providing feedback functions allows developers to report errors, gaps in the documentation, and so on, to the API manufacturer.

Role of the Technical Writer

The tasks of the technical writer in API documentation projects depend on the writer's programming skills. There are technical writers who are able to write code samples and sample programs themselves. Programming knowledge is very useful, especially for complex software products. However, it is not mandatory to be a software engineer yourself if you want to write documentation for software engineers. It is mandatory, however, that you have a solid understanding of software programming, of object-oriented programming languages, and of modern development methods, such as agile.

The strengths of technical writers, and thus the real benefit for API documentation projects, lies elsewhere: technical writers are able to structure information, to write from user- and task-oriented perspectives, and to guarantee the use of a consistent terminology throughout the complete product documentation. These assets make technical writers indispensable for API documentation.