Mike Jang - Minimum Viable Documentation for RESTful APIs

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 22 April. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Mike Jang

Technical writer at GitLab

Mike's presentation



Mike's slides

What is MVD (Minimum Viable Documentation)?

  • Similar to the MVP (Minimum Viable Portal) template.
  • More than just reading code or having a bunch of endpoints.

  • All is about Developer eXperience:
    • Developer eXperience is an inverse function of API friction.
    • Friction in your APIs includes any possible problem in your docs.
    • The secret to get to a good Developer eXperience is to have an at least good User eXperience: DX = f (UX).

  • For really good docs:
    • Endpoints are the foundation.
    • Present practical experience, give users practical situations, such as use cases.
    • Write for people who don’t read but scan.
    • Focus key info in the first 2 paragraphs.
    • First 3-5 words are critical to evoke interest.

Perspective and DX

How to walk in the shoes of your readers?

MVD details:

  1. What is this? - Landing pages
  2. How do I get started? - Tutorials
  3. Do I know all the details? - Reference
  4. Is somebody still working on this API? - Blog

The question you want to answer in your documentation is “Why would anyone use my API?” The answer is MVD. Keep it simple, so your readers can tell if your API works for them - in seconds.

1. Landing pages: What is this?

Create a clear and easy-to-find landing page layout for your use cases, products, and endpoints with direct instructions on how to get to the endpoints.

Takeaway: If your user experience makes your user think, you are doing it wrong.

Action plan: Lay out API functionality and coordinate it with your use cases.

2. Tutorials: How do I get started?

Serve the whole audience all at once, but give customers customized instructions for their particular needs.

Serve your use cases like in a buffet:

  • Help people see what is available.
  • Let the customer pick what they want.

Action plan:

  • Provide use cases, in a story: Real World Tutorials reflect real world examples and results.
  • Custom URL, code samples: Let your customers customize what you provide.
  • Custom playgrounds for testing: When you integrate API endpoints into the test environment, you enhance DX.

3. Reference doc: Do I know all the details?

  • Make it easier to look under the hood of your API:
    • Provide a UX that is equivalent with the clearness of the Swagger 2.0 Petstore endpoints.
  • Make more beginner users realize they can get this API work as well.
  • Organize endpoints to help people find what they need.
  • Provide copyable cURL commands.
  • Enable demo environments with quality UX:
    • Easy and clear UI,
    • Good UX leads to Good DX.

Takeaways: Swagger/OpenAPI Initiative reference documentation isn’t enough.

Action plan:

  • Explain the basics.
  • Organize the endpoints (no walls of text).
  • Minimum requirement: curl.
  • Enable demo environments.
  • Respect the DX.

4. Work in progress: Is somebody still working on this API?

New hope for your users:

  • Release notes:
    • Describe what’s new, describe what’s changed.
  • Blog:
    • Talk in a relatable and conversational way.
    • Go beyond your documentation.
  • Road maps:
    • Provide your future plans and show commitment.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.