[API как продукт] Documentation

This is chapter 30 my free API book.

Unfortunately, many API developers pay woefully little attention to the reference documentation; meanwhile, the documentation is nothing less than the face of the product and the entry point into it. The problem is exacerbated by the fact that writing at least satisfactory documentation from the point of view of developers is incredibly difficult.

Before we move on to describing the types and formats of documentation, I would like to say a very important point: users interact with your API help in a completely different way than you imagine. Remember how you yourself work on a project: you follow very specific steps.

  1. It is necessary to establish (the sooner the better!) whether this service is suitable in principle for your project.

  2. If so, then you need to find how to solve a specific problem with it.

In fact, beginners (i.e., those developers who are not familiar with your API) usually want exactly one thing: to compose code from existing examples that solves their specific problem, and never return to this again. Of course, it doesn’t sound very attractive in terms of the effort and time that you spent on developing the API and documentation for it, but the harsh reality looks like that. By the way, this is also why developers will always be dissatisfied with the quality of your documentation – since it is absolutely impossible to foresee all possible options, which combinations of which examples newcomers need, and which specific terms and concepts in the example will turn out to be incomprehensible to them. Let’s add to the above the consideration that non-beginners, that is, developers who are already familiar with the system and are looking for solutions to some complex specific cases, are just completely useless combinations of simple examples, and, on the contrary, they need detailed materials on advanced API functionality. .

Introductory remarks

Documentation often suffers from bureaucratic writing: it is written with strict terminology (often requiring the study of a glossary before reading such documentation) and inflated for no reason – so that instead of a simple two-word answer to a user’s question, a paragraph of text is obtained. We categorically condemn this practice: ideal documentation should be simple and concise, and all terms should be provided with transcripts or links directly in the text (however, simple does not mean illiterate: remember, documentation is the face of your product, grammatical errors and liberties in using terms are unacceptable here ).

However, keep in mind that the documentation will also be used to search through it – thus, each page must contain sufficient sets of keywords to be in the search. This is somewhat contrary to the requirement of conciseness and compactness, but this is the way.

Types of reference materials

Specification / handbook / reference

Any documentation begins with the most formal description of the available functionality. Yes, this type of documentation will be as useless as possible from the point of view of ease of use, but it is impossible not to provide it – the reference book is a hygienic minimum. If you do not have a document that describes all the methods, parameters and settings, the types of all variables and their valid values, all options and behaviors are fixed – this is not an API, but just some kind of amateur activity.

Today it has also become a standard to provide a machine-readable reference – according to some standard, for example, OpenAPI.

The specification should contain not only formal descriptions, but also document implicit conventions, such as, for example, the sequence of event generation or non-obvious side effects of methods. The reference should be considered as the most complete of possible types of documentation: having studied the reference, the developer will have to learn about absolutely all the functionality available. Its most important applied value is advisory: developers will turn to it to clarify some non-obvious issues.

Important: formal specification is not the documentation itself; documentation is the words, which you will write in the description field for each field and method. Without verbal descriptions, the specification is only good for checking whether you named the entities well enough for the developer to guess their meaning on their own.

Recently, descriptions of the nomenclature of methods are also often laid out in the form of ready-made collections of requests or code fragments – in particular, for Postman or similar tools.

Code examples

Based on the above, code examples are the most important tool to attract and support new users of your API. It is extremely important to choose examples in such a way that they make it easier for beginners to work with the API; poorly structured examples will only degrade the quality of your documentation. When compiling examples, the following principles should be followed:

  • examples should cover actual API usage scenarios: the better you can guess the most common developer requests, the friendlier and easier to enter your API will look in their eyes;

  • examples should be concise and atomic: mixing many different tricks from different subject areas in one code fragment sharply reduces its understandability and applicability;

  • the code of the examples should be as close as possible to the real application; the author of this book faced a situation where a synthetic piece of code, absolutely meaningless in the real world, was mindlessly replicated by developers in huge numbers.

Ideally, examples should be linked to all other types of documentation. In particular, the reference should contain examples that are relevant to the description of the entities.


Examples will become much more useful for developers if they are presented in the form of “live” code that can be modified and run for execution. In the case of library APIs, this can simply be an online sandbox with pre-prepared examples (existing online services such as JSFiddle can also be used as such a sandbox); for other APIs, sandbox development can be more difficult:

  • if access to data is provided through the API, then the sandbox should also allow you to work with real data – either your own (tied to the developer’s profile), or with some test data set;

  • if the API is an interface (visual or software) to some non-online environment (for example, graphics libraries for mobile devices), then the sandbox should be a simulator or emulator of such an environment, in the form of an online service or standalone application.

Guide (tutorial)

By leadership, we mean a specially written human-readable text that outlines the basic principles of working with the API. The manual, therefore, occupies an intermediate position between the reference and examples: it implies deeper than just copying pieces of code from examples, diving into the API, but requires less investment of time and attention than reading the full reference.

By definition, a manual is such a “book” in which you convey to the reader how to work with your API. A well-written manual, therefore, should roughly follow the principles of writing books on programming, i.e. present concepts consistently and consistently from simple to complex. In addition, the manual should include:

  • general information on the subject area; for example, for mapping APIs, the manual should contain an introductory part about coordinates and working with them;

  • correct use cases, i.e. “happy path” API;

  • descriptions of the correct reaction to certain errors;

  • detailed tutorials on advanced API functionality (with detailed examples, of course).

As a rule, the manual is a general block (basic terms and concepts, notation used) and a set of blocks for each kind of functionality provided through the API.

Often in the composition of the leadership stands out the so-called. ‘quick start’ (‘Hello, world!’): The shortest possible example that allows a beginner to build at least some minimal application on top of the API. There are two purposes for its existence:

  • become the default entry point, the most understandable and useful text for those who first heard about your API;

  • involve developers, let them “feel” the service on a live example.

Quick starts are also a great indicator of how well you’ve done in identifying frequency cases and developing helper methods. If your quick start contains more than a dozen lines of code, you are definitely doing something wrong.

FAQ & Knowledge Base

After you publish the API and start supporting users (see the previous chapter), you will also have an understanding of the most common user questions. If it is not so easy to integrate the answers to these questions into the documentation, it makes sense to create a separate section with frequently asked questions (FAQ). The FAQ section must meet the following criteria:

  • answer real user questions

    • you can often find such sections that are not compiled based on real requests and mainly reflect the desire of the API owner to once again convey some important information; of course, such a FAQ is useless at best and annoying at worst; for ideal examples of the implementation of this anti-pattern, you can refer to the website of any bank or airline);

  • both the question and the answer should be formulated concisely and clearly; in the answer it is acceptable (and even desirable) to link to the relevant sections of the guide and handbook, but the answer itself should not exceed a couple of paragraphs.

In addition, the FAQ section is very well suited to explicitly communicate the main benefits of your API. In the form of a question-answer pair, you can clearly describe how your API solves complex problems beautifully and conveniently (or at least solves it at all, unlike competitors’ APIs).

If you provide technical support publicly, it makes sense to save questions and answers as a separate service in order to form a knowledge base, i.e. a set of “live” questions and answers.

Offline Documentation

Although we live in the world of the winning online, the offline version of the documentation in the form of a generated document is nevertheless useful – primarily as a “cast” of the current state of the API at a certain point in time.

Duplicate Content Issues

A big problem for the readability of the documentation is API versioning: many texts for different versions are similar to the point of indistinguishability. It is very difficult to organize a high-quality search on such an array of data, both internally and externally. Good manners in this regard are:

  • explicit and noticeable highlighting on the documentation pages of the API version to which it refers;

  • a clear and conspicuous indication of the existence of a more up-to-date version of the page for new APIs;

  • pessimization (up to the prohibition of indexing) of documentation for outdated API versions.

If you support backwards compatibility, then you can try to maintain the same documentation for all versions of the API. In this case, for each entity, you need to indicate from which version of the API its support appeared. Here, however, the problem arises that it is extremely difficult to obtain documentation for a particular (outdated) version of the API (and in general to understand what features a certain version of the API provided). (But the offline documentation we mentioned above can help with this.)

The problem becomes more complicated if you maintain documentation not only for different API versions, but also for different environments/platforms/programming languages ​​- let’s say your visual library supports both Android and iOS. In this situation, both versions of the documentation are completely equal, and it is impossible to single out one of them to the detriment of the other.

In this case, you must choose one of two strategies:

  • if the help content is completely identical for all platforms, i.e. only the syntax of the code changes – you will have to prepare the ability to write documentation in a generalized way: documentation articles should contain code examples (and, possibly, some notes) for all supported platforms at once;

  • if the content, on the contrary, is significantly different (as in the mentioned Android/iOS case), we can only offer to spread the sites as much as possible, up to the establishment of different sites: the good news is that developers almost always need only one of the versions, another platform is their absolutely not interested.

Documentation quality

It is important to note that the documentation is as convenient and useful as possible if you consider it as one of the products in the API services line – which means that you analyze user behavior (including by automated means), collect and process feedback, set KPIs and work on their improvement.

Was this article helpful to you?

Not really

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *