On Documentation-Driven Development

I love designing and developing APIs. In building a great API, the design and development processes demand equal attention. The problem is that popular development approaches don’t emphasize the design process. You may be familiar with the concepts of test-driven development (wiki) and behavior-driven development (wiki), but let’s talk about the lesser-known concept of “documentation-driven development” (no wiki).


It all starts with the README. Your README is your code’s most important work of documentation. It has the ability to give a high level view of your code, communicating its overarching purpose. That purpose is much more difficult to communicate via code comments.

Tom Preston-Werner, co-founder of GitHub, wrote a fantastic blog post about the merits of readme-driven development. This approach is your best bet for 90% of projects.

So, what projects make up the other 10%?


Designing an API is a special case because you’re often designing for unknowns. You might not know:

  • what types of clients will consume the API or their individual preferences
  • the flow that any given consumer will take through your API endpoints
  • which information will be most valuable to the consumer

With all of these unknowns, the best thing you can do for yourself and your consumers is to write your documentation first, as visibly as possible. The goal is to gather insight and recommendations from your consumers early and throughout the design process, turning your unknowns into knowns. Changes are easier and faster to make in documentation than they are in code.

The workflow is:

  1. Write or update documentation
  2. Write a failing test according to that documentation (red)
  3. Write code to pass the failing test (green)
  4. Refactor

Our Experience

At Collective Idea, documentation-driven development has been wonderful for writing APIs. We’ve seen several benefits:


Oftentimes, we will write an API for a dedicated consumer such as an iOS app. Writing documentation first provides a space in which server and client teams can collaborate. The documentation also gives the client team something to work from before the server team has even implemented the documented endpoints. This prevents rework and parallelizes the efforts of the server and client teams.


Accurate and up-to-date documentation is important for an API, especially a public API. When writing or updating documentation is a required first step of your development process, you ensure your documentation is always consistent with your code.


Documentation-driven development elevates writing documentation to the same level of importance as writing code. As a result, documentation changes are also included in the peer review process. This gives the reviewer insight into the “why” behind a set of code changes. Code review is much more effective when the reviewer has this understanding of purpose.

Whether or not you’re writing an API, give readme-driven or documentation-driven development a shot and let us know about your experience.

Collective Idea is using documentation-driven development to build the API for Dead Man’s Snitch, our tool for monitoring cron jobs and other recurring tasks. Check it out!

Steve Richert


Post a Comment

(optional — will be included as a link.)
  1. What tools are you using for writing api docs?

    April 22, 2014 at 8:41 AM
  2. Rob: Nothing special! We use our editor of choice and write our documentation in Markdown documents within the repo or in the repo’s wiki. We’ve looked at tools that automatically generate documentation, but we’ve found that good old fashioned writing gets the job done best.

    Steve Richert
    Steve Richert
    April 22, 2014 at 14:42 PM
  3. I like also this approach, but what about later updates? How do you guarantee that the documentation is updated?

    April 25, 2014 at 4:48 AM
  4. Hannes: You use the same workflow, updating your documentation to reflect the upcoming change, as your first step. There are no automated checks or assurances when you’re writing your own docs. You have to be intentional and vigilant. Documentation needs to be part of the expectation during code review. A pull request with no docs should feel as dirty as one with no tests. That comes with practice.

    Steve Richert
    Steve Richert
    April 25, 2014 at 8:33 AM