Minimum viable documentation for APIs

Minimum viable documentation set (MVD) is the smallest amount of documentation needed so that the majority of developers willingly adopt an API, just enough that they don't feel overwhelmed by frustration or give up because the API wastes their time.

When frustration is high, it's because information is missing, incomplete, or too hard to find. For example, there are no code samples, or no tutorials, or sometimes, no information about how the API works on a high level.

The MVD includes the most critical information that new users need in order to get started and categorizes it in a way that makes things easier to find and use.

Here are the three document types that you need in order to have minimally viable documentation for an API:

Reference. For REST APIs, this means complete catalog of endpoints, their methods, the parameters that can be used for the request, and the attributes that can be returned in the response. For the reference section, completeness and accuracy are critical. Nothing infuriates users like a parameter with no description at all.
A quickstart or Getting Started document. This should show users the shortest path to completing whatever task the API helps them with, so they can understand how it works and appreciate the benefits.
An overview that explains what the API does, how it works, what problem it solves, and any other high-level information the user might want to understand before adopting the API.

There are compelling reasons for this architecture, with exactly three parts, as opposed to one or four.

Different kinds of users

Firstly, all three types of documentation are needed, because there are different types of users, and different users bring their own expectations.

Some APIs offer only reference information, but this doesn't isn't enough to please every potential user of the API. (The reference section is seldom, if ever, left out but will turn users away if it lacks completeness.)

API users have different ways of getting started and different ways of using the docs. Some developers go straight to work with code that they copy from the reference section and modify. Some follow a tutorial or quickstart, and then try to leap from the example task into a real task after they have finished. A small number are unwilling to adopt an API until they can look at the overview (and possibly some support information).

Attention to how developers get started with the API is important, because most of the pain in using any technology is in the beginning. It's important to make sure that users have the right kind information so that they don't walk away and try some other product, and it's important to make learning easy enough that they don't give up.

Different kinds of information

It's no coincidence that there are exactly three documents in this set and not one or two. You might wonder why all the information that developers need can't be dumped into a single document that contains everything.

The three documents in the MVD correspond to information types that are natural to all kinds of technical and non-technical writing, and because of the way people use them it's best to keep them separate.

First, here are the types:

Conceptual information: A more open form used to explain ideas. Conceptual information isn't as structured as the other two types, and its goal is understanding. In the MVD, the Overview contains most of the conceptual information.
Reference information: Any dictionary-like collection of consistently structured entries, usually consulted when the reader wants to look up a precise item of data. In the MVD, the API Reference section contains all the reference information.
Task information: A set of steps that tells the reader how to complete a task when the reader's goal is to get something done. In the MVD, this would be the quickstart.

Joanna Bujes had a unique way of introducing these concepts when she taught software technical writing at UC Berkeley Extension in 2016. One evening early in the fall semester, Bujes (now my manager at Synopsys Software Integrity Group) walked around the small classroom with an armload of books that she said were from her own shelves. In front of every student she placed a different cookbook. Professor Bujes pointed out that, just like technical documentation, each cookbook used the three information types introduced above.

Conceptual information: Introductory chapters explain things such as how to select and store meat, fish, produce, and other ingredients; what kind of equipment to use for baking bread, and how to handle dough.
Reference information: For example, a table correlating pounds of fruit to the number of quart jars needed to preserve them.
Task information: Every cookbook contains step-by-step instructions for cooking numerous recipes.

The cookbook is a good analogy for technical documentation, because it demonstrates that the typology that divides material into concept, reference, and task is an organic and natural way to organize information. The use of these three types makes it easier for readers to find the information they want, when they want it.

In other words, readers most likely use reference, task, and conceptual information at different times and for different reasons. Keeping them separate means not only that readers know where to look for the information that they want, but that they don't wade through unnecessary information, unrelated to the task at hand.

To use the cookbook as an example, a significant number of users might want to read the nine-page explanatory article that begins the bread chapter in The Joy of Cooking -- it explains how to mix bread dough; how to knead and proof correctly; how to achieve hard, soft, or glossy crust; and how to shape dough into loaves. Frequent users might eventually consult the five-and-a-half page reference section that runs down numerous kinds of flour (The following are just the wheat flours: all-purpose, cake, bread, presifted, pastry, instant, self-rising, semolina, farina, whole-grain, bran, cracked wheat, gluten flour, wheat germ flour, triticale flour. Then there's an entire listing of non-wheat flours.)

Imaging trying to bake bread if the author had combined all that information with the recipes, most of which run a half page or less. It would be a longer and more difficult task to follow an individual recipe, because you'd have to skim all the superfluous information mixed in with the actual steps. And later, if you wanted to know the difference between whole-grain flour and bran flour, you'd have a heck of a time remembering where you'd seen each of them.

For the same reasons, we avoid mixing conceptual information, reference information, and task information when we write software documentation.

The Payoff: What the MVD does for your docs

The eventual payoff for thinking about MVD when you work on the docs is two-fold:

A big increase in learnability in the short term
A moderate increase in usability for ongoing users over the long term

Increased learnability

Learnability is a golden metric for adoption of the API -- and the MVD is all about learnability. It ensures that the key information is present for various kinds of users in various kinds of situations, and thus provides all of them with what they need to get going.

One reason that learnability is such a big deal in software documentation is that most of the pain in using software is right at the beginning. If people are going to get frustrated and quit using your software, that will most likely happen a short time after they start; the best way to increase the number of users is to make it as painless as possible to get going.

Because people tend to choose software that makes it easier to get going, people who make APIs have been discovering that effective documentation is a revenue driver, because whoever has the best docs can leverage it to win the best deals. (Stripe is a good example of a company that leveraged developer experience to grow its footprint in the market.)

Increased usability for ongoing users

While it's important to get users to the onramp, there's also the ongoing usability of the reference docs, after they've been adopted. The MVD model continues to pay dividends for these reasons:

Thoroughness of the reference docs is a cornerstone of the MVD and is also important for ongoing usage.
Applying MVD means organizing information into concepts, tasks, and reference, so that it's easier for users to find what they need when they need it. The findability saves time and effort.

What the MVD doesn't do

The MVD is a framework to start a new set of docs or assess existing documentation for completeness. Don't assume that it answers all the questions you might have about your documentation. Here are some things it does not do:

Measure quality. The MVD tells you whether all the minimal elements are present, not whether they are well-written. (More on that later.)
Measure maturity. As your product matures, your documentation should mature along with it. Once you have the minimum amount of documentation, you will soon decide that it isn't enough. In addition to a quickstart, users will want you to add more tasks to cover the workflows that they use to get things done. Mature documentation has all the elements of the MVD -- and more.
Provide long-term documentation architecture. Three simple sections might be fine in the beginning, but later your documentation will become more complex, and you'll have to come up with a sensible way to organize it. Think of the cookbook again: The Joy of Cooking has expanded over the years to include thousands of additional recipes, and chapters discussing cocktails, frozen desserts, and basic ingredients have been added, removed, and then restored. A quick look at the table of contents (of The Joy of Cooking or any other well-designed book) will demonstrate that the organizing principle must always be the needs of the user. Who are the readers? What do they want to accomplish? What do they need to know in order to do that? In what order will they need to know?