Home
Technical Writers
> For writers who need to understand the challenge of documenting APIs for developers.
Documentation Design and Quality
Beyond MVD
If you have sized up your API and written all the docs you need for MVD, you have come a long way, but there's more. (Like software, documentation is never done.)

Technical Writers
> For writers who need to understand the challenge of documenting APIs for developers.
- For beginners
- Documentation Design and Quality
  - Minimum viable docset
    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.
  - Complete the MVD project
  - API reference
    The largest and most important part of the reference documentation is the section that describes all of the API endpoints.
  - API reference example
    The following is a reference entry for one endpoint on a fictional API. This is just one way to represent all the necessary information.
  - Working with OAS3 and Swagger
    It's easy to assume that the OAS3 spec results in documentation with more accuracy or completeness compared to documentation that isn't programmatically generated. Not necessarily. The spec is ultimately written by humans, and information can be missing or incorrect.
  - Writing the overview
    If the project is brand new or hasn't had a technical writer before, it most likely lacks an overview. You should write one.
  - Writing the quickstart
    A quickstart helps new users get through their first experience using software.
  - Beyond MVD
    If you have sized up your API and written all the docs you need for MVD, you have come a long way, but there's more. (Like software, documentation is never done.)
  - The how-to article
    A how-to article is a set of steps that describe how to accomplish one particular goal.
- Tools and toolchains
- Resources

Beyond MVD: Expanding your documentation as the product matures

If you have sized up your API and written all the docs you need for MVD, you have come a long way, but there's more. (Like software, documentation is never done.)

How-to articles are the next step

After a user is beyond the getting-started stage with an API, they need additional documentation, mostly in the form of how-to articles.

The docs will still grow steadily as the product matures, and most of the growth in API docs, other than reference, should be how-to articles. These are step-by-step articles that explain how to accomplish a particular task.

Your quickstart article might have covered the basics, but the list of how-to articles needed by your users will continue to grow as the API grows.

Why the how-to articles are important

A how-to tells your users how to accomplish a complex task, usually one that requires a series of calls made to a number of API endpoints, in the right order, and by including the right data in each request.

It's often difficult to figure out the steps needed to accomplish what you want with an API, when the only guide you have is the reference docs.

Offering the right how-to articles saves your users time and spares them the frustration of working it out on their own.

Final thoughts

Ideally, a set of how-to articles will include a body of tasks that covers what the majority of users wants to do with your API, most of the time. (Unless you have an army of technical writers, 100 percent coverage can be elusive.)

Prioritize the articles that will give the most help to the largest number of users.