How to write great API documentation: examples, practices & tips
Great technical documentation step by step
Before we start writing the technical documentation for our application…
The introduction is full of clichés, which — as it turns out — are not clichés at all
Hardly any programmer likes writing technical documentation, and this article is not going to convince you that writing API documentation is the coolest task in the world.
We are only asking you one thing — do not start writing documentation with the following mindset: `
‘It was hard to write an application,
let it be difficult to understand it.’
After all, technical documentation should be like a user manual of IKEA furniture — specific, clear, dispelling doubts, showing the user step by step where to insert which screw and how to use the assembled equipment.
And if you agree to the first request, we have the second one: don’t put off writing technical documentation ‘until the last minute’. Nothing good ever comes of it. First, after three months of programming, even your own code will look foreign to you. Secondly, the documentation written carelessly will only cause that in the following months, the inbox of the technical support will multiply with unfriendly e-mails from nervous programmers who have spent hours of their time solving a problem and do not care that “it works for me” because it doesn’t work for them and something is wrong with the documentation.
Instead, make a good habit into your workflow: spend 2–4 hours each week creating and updating documentation. Make this time clearly written in the team’s work schedule.
How to write great API documentation
Step 1: Understanding who is really the recipient of the documentation, i.e. choosing a writing style
There are three basic situations when someone opens your documentation:
- He is curious how the application works and what it offers
- Really want to start using it
- While using the app it got stuck at some stage and needs some help
In other words, either a decision-maker or Project Manager or — much more often — a programmer whose task is to implement the application on the client’s side will land on your technical documentation page.
Therefore, we recommend that you write technical documentation as if its readers were programmers.
Hence, the style of writing documentation should be technical and specific. Use short, meaningful sentences without embellishments. The whole thing must be legible at first glance and logical.
How to write great API documentation
Step 2: Necessary elements of technical documentation, i.e. creating a table of contents
Every application is different. One is shorter, the other is longer. Hence, some technical documentation takes two A4 pages, while others resemble the Britannica Encyclopedia in its volume. However, there are basic elements that are assumed to be included in any technical documentation.
What must be in technical documentation:
- introduction, i.e. a description of the method of operation (specifically: what this app does)
- how to install the application and dependencies
- algorithms used
- the arrangement and operation of the individual components
Therefore, what we need to do at the beginning of writing technical documentation is to draw its table of contents. What, where and in what order, so that every important element can be easily and quickly found, regardless of whether we are looking at this documentation for the first time, trying to start using it or returning to it after years with a bug.
Below, we throw in some inspiring examples of the table of contents of technical documentation that impress with their readability and user-friendly navigation.
The table of contents of the technical documentation — examples
Example 1. Heroku Dev Center
Heroku technical documentation is one of the best examples on the market in terms of table of contents.
We see the main categories right away — from architecture through databases, security, command lines and add-ons to support languages. Below the main links, we also have all the elements included in each of the main categories listed in three columns. No unfolding or collapsing elements. Everything served on a tray.
Example 2. Laravel
Laravel offers a completely different layout for the table of contents (but just as convenient to use).
The main categories are listed on the left sidebar of the documentation page, and each category and its menu are opened with a plus. The submenu we are currently on is additionally highlighted in red, which makes navigation easier.
How to write great API documentation
Step 3: Describe the individual components and include application examples (including code snippets!)
Once the menu of our technical documentation of an application is in order, we move on to describing the individual elements.
At the beginning, an introduction, i.e. a few sentences explaining what the application is for.
This can be done in one paragraph describing a basic operation, such as a Stripe Sigma:
Or we can describe the whole thing in one simple sentence, eg ‘This application allows you to access the YXC database, on the basis of which you can predict how many gifts you will get from your friends in the next year’.
Then we go on to describe the specific methods of the program’s operation and the commands used.
Importantly, each command should be supported by an example with a code!
Why? The rationale is simple:
- Examples explain the principle of operation faster than extensive text descriptions, and since the readers of our technical documentation are programmers, they will certainly appreciate pasted fragments of code
- Code examples also include ready-made copy-paste elements. In this way, users can put the rulers into practice right away without having to work out everything on their own
Description of operating methods with the code fragment pasted — examples
Useful tip:
It is worth grading the methods from the easiest to the most difficult. In this way, only after 3–5 easier examples (e.g. authentication test or simple request) we describe more complicated methods used in API. As a result, the programmer is first encouraged by the successes of the first attempts, and only then faces more difficult challenges. It is easier for him to process new information.
How to write great API documentation
Step 4: Don’t be afraid to reach for useful tools, i.e. which technical documentation generators are worth using
You don’t always have to do everything manually. We do not live in the 17th century;) Technical documentation generator is an invaluable tool that automatically converts source files for us and puts them into HTML or any other output file. This significantly speeds up the creation of technical documentation.
In recent years, technical documentation generators have appeared on the market more and more. Here we suggest which in our opinion are currently in the forefront.
TOP 3 free technical documentation generators that provide support for programming languages such as. incl. C ++, C, Objective-C, C #, PHP, Java, Python and IDL:
Certainly one of them will win your heart ;)
‘Win-Win situation’ — both you and your customer win
Benefits of well-written technical documentation:
- Fewer requests for technical assistance (solving technical problems usually takes longer than writing API documentation!)
- Exchange of negative e-mails for positive ones (we do not spoil the blood and mood of our clients and we do not raise our pressure by reading the complaints)
- We have a decent foundation for the development of new products (scaling and such strategically important stuff for the development)
- Satisfied customers, and therefore more referrals, more contracts and more profit for the company.
