Writing API documentation that developers won't hate

Pradeep Sharma ✔ -

API documentation is the #1 factor that impacts the adoption of your APIs. If you want to grow the adoption of your APIs, you want developers to be able to

  1. Get started quickly
  2. Put the API to use with the least chances of failures

Before diving into the details of how you should write the documentation, let's investigate from the perspective of a developer who just landed on your API documentation page

The ideal journey of a stranger to becoming a champion API user

Before this stranger becomes a champion API user, they are a learner.

Good API documentation makes the learning experience rewarding, fun, and engaging


Here's a framework to make this learning journey great, from beginner to champion level

  1. Get their attention by answering - why should they care about this API?
  2. Get them invested in learning by quickly getting them to the first "Joy of Making" using your APIs.
    A good tactic to do so is to use "Dumb Examples" (Inspiration: Stripe Docs - Get Started -> Clone a sample project)
    Note: "Dumb Examples" are the examples that serve everything to build and feel accomplished quickly(hint: copy-paste). They are dumb from the perspective of a champion API user. But from the perspective of a new user, these examples make them feel powerful because of what they can do with your APIs with almost no effort.
  3. Explain the building blocks used in "Dumb Examples" by "Hand-waving"
    Note: Explaining too much, too early leads to mental fatigue. Hand-waving is a technique where you either skip explaining some important fundamental concepts or explain them in an oversimplified language. You do so to get the learner get a high-level overview. During this initial phase of learning, prioritize understanding over accuracy.
  4. Introduce them to tutorials that explain concepts in a  structured manner for most popular use cases(Inspiration: Gatsby Tutorials)
  5. Provide a structured reference for advanced usage (Inspiration: Stripe API). Here we are prioritizing accuracy over understanding. This is the final source of truth for the API users. A simple mistake here can lead to bugs.
  6. Provide them a support channel where they can get answers to their questions
  7. Provide them a channel where they can celebrate their small wins while learning about the APIs. This is also a channel for them to get inspired.

We move from the least amount of abstraction(i.e. less flexibility to be creative beyond the scope of the example) at Step 1 to the maximum amount of abstraction at Step 5(i.e. maximum freedom to be creative).

Writing the documentation

To write the documentation just turn the above workflow upside down.

Start with

  1. Dogfooding
    (This will build foundation for step#7 of Learner journey)
    The API development team builds some showcase projects using their API components and shares them in the #celebration channel
  2. The support
    (This will build foundation for step#6 of Learner journey)
    Team asks each other questions in the support channel to learn more about the API and make their showcase project better
  3. The source of truth
    (This will build foundation of #5 of Learner journey)
    Team creates accurate reference documentation of the APIs, everyone writes about the parts they had written and then organize everything
  4. The tutorials
    (Achieves the step#4 of Learner journey)
    Team uses API reference docs to create a tutorial for some of the use cases that a stranger will be able to connect with
  5. The hand-wave for building blocks
    (Step#3 of Learner journey)
    Team explains the concepts used in their showcase examples built in step #7 of learner. Think of a user who might not yet know about your API at all. Simplify.
  6. The instructions
    (Step#2 of Learner journey)
    Team simplifies the showcase example and put together minimal notes to make sure a developer that doesn't know the project yet can set it up on their machine easily
  7. The package
    (Step#1 of Learner journey)
    Put together the homepage with a tagline that attracts strangers to explore the project with some quick links to try out the examples, and connects everything from Step 1-7

Improving the documentation

After a great start of writing the documentation, you would want to iterate to make things better

  • Review API documentation usage and prioritize the next action items
  • Make the navigation better, make it easy to find the right pages within the website
  • Review questions people ask in support channels
  • Allow documentation users to give you feedback about the documentation(Inspiration: Mongodb docs)
  • Work on search engine optimization to get people to the right pages when they search on google(or any other popular search engine)
  • Follow good version practices and have an easily discoverable CHANGELOG. (Inspiration: Electron release notes). Help the user choose the right version and make a quick decision whether to upgrade or not. A good inspiration for this - mongodb docs(notice how they share "starting in version 4.4" in the documentation against each feature - it helps people make good decisions).
  • Think about communication strategy to handle deprecation notices. Think about how you can let the API users know about the deprecation faster and more frequently. Can you build SDKs - so that you can highlight the deprecation notice right when developers integrate APIs? What alternative communication channels(e.g. email, blog, etc.) should you use to remind users about the deprecation?

Conclusion

We acknowledge that an individual's willpower to learn is limited. So we destructure their learning journey into tiny building blocks. We build their understanding of the APIs from level 0 to level 1, then to level 10, and then eventually to level 100.

After we understand these user's learning journey milestones, we prioritize the tasks mentioned in the article to start writing good documentation and keep moving towards better documentation, one level up at a time.