The process for completing your MVD project

Order of operations

When establishing minimum viable documentation for your API, complete the project in this order:

1.) Reference docs. They have to be finished before you can write the other docs. And your users can't access the APIs unless these docs are 100 percent complete. Therefore, if you are starting from scratch, complete the reference docs first. If you are improving your documentation, make the review of your reference docs the first part of the process.

This step can take a considerable amount of time, depending on the size of your API and resources available. Give the reference docs as much time as necessary -- the good will of users depends on the thoroughness of your review.

2.) The quickstart. If you don't have one, it's the next step after the reference docs. It will be critical for adoption of the API and for onboarding new users, and that makes its importance second only to the reference guide.

3.) The overview. Of the three main documents, write the overview last, for the following reasons:

  • You'll understand the API and its users better after thinking about the other docs.

  • Although the overview is critical for some users, it's a smaller number of users than the other two documents -- it can be a strong preference to have the overview whereas the reference is a necessity for every single user.

4.) Review the rest. If you are improving an existing set of documentation, review the remaining docs and separate the concepts, tasks, and reference. For example:

  • Provide How-to articles that only tell the user how to do one thing, and that describe it in a set of specific steps, without pausing to explain concepts.

  • Any concepts that need explanation can be extracted into a freestanding article, which you can link to whenever needed.

  • Move reference information into small articles that only contain one reference topic. Then group the reference articles together in one place. In addition to the usual API reference entries, you might have some short articles that explain things like error codes, rate limiting, and the means for filtering responses that contain large amount of data.