How to Start Writing API Technical Documentation (with templates)

Let’s say you’ve been asked to document a set of APIs, a new area for you. Where do you start? At first this can seem overwhelming. So many new acronyms, terms, jargon, and pieces to fit together. Here’s a suggested approach.

DOWNLOAD API Reference Documentation Template

Get API Reference Documentation Template

If your company develops APIs, use this MS Word template to write reference documentation for each API. The API documentation describes the common components used by each of the APIs for iOS, Android, and other platforms. Use the API reference documentation to explain the data structures available through the APIs.

How to Starting Writing API technical documentation

#1 Focus on a specific API, for example, REST or Web.

Ignore the temptation to read others, you’re goal is to build a body of knowledge in one area. Once you’ve build this, others will be easier.

#2 Start with the foundation first. Don’t skip. The key is to understand the concepts, not look for definitions or examples. Ask yourself as you go along: do I understand a class, a method, abstraction and so on. If you don’t, go back. Skipping ahead defeats the purpose.

#3 Download Quick Sharp or some other API development tool. I see this to learn to code C Sharp. Its free and there are many code samples out there. As you read, type in the code sample by hand. I know copy and pasting is quicker but try and type if you can. You’ll get a better feel for the code and a nice sense of satisfaction when it works.

DOWNLOAD API Reference Documentation Template

#4 Google API documentation sets. You should be able to find a few really good sites. Notice what they have in common. These are the sections you’ll need to cover too. Study the layout format and content. Use these as a framework for your API docs.

#5 Code samples are important. Why? Because this shows the developers exactly how it works. If written correctly, it helps them get started. The conceptual stuff is fine too but code samples put the meat on the bones, so to speak. Add lots of comments, color code where necessary, and use meaningful names for methods, classes, and properties.

How to Write API Documentation Tutorial

#6 Don’t forget prerequisites. For example, a module they need to install, a parameter they need to set, or some other setting.

#7 Provide meaningful definitions. For example, when describing a parameter, don’t state the obvious, instead provide that extra information that puts the parameter definition in context. Likewise, highlight the default setting and mandatory parameters.

If you think about it, your API doc serves two purposes.

• Developers who want to know how a specific setting works. Let’s say they want to use a parameter. What impact does it have if a specific setting is made?
• Examples of how to get started. These help the developers get to grips with the API and, if written correctly, you can use too.

Finally, only write what you understand.

Always make sure you can stand over what you right. If confused, ask for help. Everyone starts somewhere.

DOWNLOAD API Reference Documentation Template

Get API Reference Documentation Template

• Use this 28-page MS Word template to document your REST/Web APIs. This template pack includes detailed examples, guidelines, and screenshots.
• You also get a 16 page How to Write API Document tutorial that explains how to write each section in your API reference documentation. It includes helpful explanatory text that walks you through the process of documenting each section in the API, including the parameters, endpoints, requests, responses, and endpoints.

You can change everything in the document – text, images, and tables. There are no special plug-ins, macros, or installation files.