From The Philadelphia Story

Documentation-Driven API Design

  • A well-designed API is easy to understand.
  • A well-designed API is easy to get started with.
  • A well-designed API requires you to learn a minimum of new concepts, rules or terminology.
  • A well-designed API leverages concepts that you already know and works in familiar, predictable ways.
  • A well-designed API requires as little documentation as possible.
  • A well-designed API obeys the Principle of Least Surprise.
  • How do I do X?
  • What’s the best way to do X?
  • Am I allowed to do Y?
  • What can go wrong? What are the edge cases?
  • Do I need to do X before I can do Y?
  • If I do X, do I need to do Y later?
  • Can I do X, Y, Z in any order?
  • What are the side effects of Y?
  • What are the performance and resource usage implications of doing X?
  • etc., etc.
  • Write the documentation for the API. You can do this as you design an API or later if you’d like to rework an existing API. Wherever the documentation becomes complicated or difficult to write, revisit the design. This process works because it is easier to spot complexity in the documentation than in the code.
  • For example, inconsistencies in your API becomes painfully clear when writing documentation. Two classes might have methods with similar names but that work in very different ways. Or they might be inconsistent about how permissive they are about their inputs, or around thread-safety, or whether errors throw exceptions or affect return values, etc., etc. Writing documentation places you in the mindset to spot these issues.
  • Another simple example is when the documentation for a class or method or property don’t align with it’s name. Naming is hard; documentation helps identify where you’ve gone astray.
  • Also look for terms in your documentation that have a meaning specific to your API. These terms correspond to concepts that you’re requiring the user to learn. Try to minimize these — and not just by rewriting the documentation, but by reworking the API itself. The cognitive burden of an API is a function of the square of the number of concepts that it requires the user to learn — and engineers are rightfully wary of assuming that burden.
  • Documentation-driven design depends on the ability to write good documentation, but simply the act of focusing on the documentation will help you cultivate empathy for the user. You’ll try to anticipate the ways a user might misunderstand your API. You’ll include warnings about gotchas and recommendations on best practices. These translate directly into ways your API can be improved.
  • In documentation-driven design, you should define documentation broadly. Show your API to others, whether in the form of a PR, a formal presentation or through hallway testing. Look at what takes the most time to explain. Pay attention to the questions your audience asks. Talk to the audience afterward and probe for misunderstandings. This will help pinpoint where the API could be improved.
  • Best of all, if your API already has users, pay close attention to what they find hard to understand — and what they complain about. If someone opens a Github issue due to a misunderstanding, don’t just close the issue — consider changing the API to prevent that misunderstanding. Thanks to everyone who has ever complained to me about an API I created; your comments (hopefully) helped.




Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


More from Medium

Perform Print Merge on Figma with Composer Plugin

Eco-sustainable Design for APPs

“No Interface is the Best Interface”

Ingredients for Better Accessibility — Part Two: Customizing the Recipe

A chef sprinkles seasoning on a sizzling pan of spicy food