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?

api-documentation-template-ms-word

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.

api-documentation-template-ms-word-pagination

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.

api-documentation-template-ms-word

API Template - Download Here

Updated: This article was originally written in Nov 2014.

Thousands of templates to jump start your project

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan