How to Start Writing REST or Web API Documentation

Let’s say you’ve been asked to document a set of REST or Web 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.

• Focus on a specific api,  for example, REST. Ignore the temptation to read others, your goal is to build a body of knowledge in one area. Once you’ve build this, others will be easier.
• 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.
• Download QuickSharp or some other development tool. I see this to learn to code C Sharp / .Net. 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.
• 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.
• 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 but code samples put the meat on the bone, so to speak.
• Add lots of comments, color code where necessary, and use meaningful names for methods, classes, and properties.
• Don’t forget prerequisites. For example, a module they need to install, a parameter they need to set, or some other setting.
• 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 documentation soc serves two purposes.

1. 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?
2. 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.

How to Write API Documentation – Free eBook

Click here if you want to 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.

API Documentation Template – MS Word

This template isn’t for expert or senior tech writers. Rather, it’s for junior tech writers, developers, or anyone else who’s been asked to document an API and needs some help to get started. The price is pretty reasonable when you think how long it would take to come up to speed and create your own writing guidelines. That’s it. Here’s what’s inside.

• 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.

Updated: This article was originally written in Nov 2014.