On Documentation-Driven Development

Putting a bit more emphasis on your README

Abstract Paper by Anastasia Zhenina is licensed under Creative Commons Zero

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!

Photo of Steve Richert

Steve is a Senior Developer working with Ruby/Rails and JavaScript. He’s an active open source contributor and the lead developer for Interactor. Steve is also involved in documenting and improving Collective Idea’s software development practices.


  1. robzolkos@gmail.com
    April 22, 2014 at 12:41 PM

    What tools are you using for writing api docs?

  2. steve@collectiveidea.com
    Steve Richert
    April 22, 2014 at 18:42 PM

    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.

  3. h.mueller@vinett.de
    April 25, 2014 at 8:48 AM

    I like also this approach, but what about later updates? How do you guarantee that the documentation is updated?

  4. steve@collectiveidea.com
    Steve Richert
    April 25, 2014 at 12:33 PM

    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.

  5. August 25, 2019 at 20:08 PM

    eing on the life, as of now to be frank.