Collective Idea

Collective Idea Logo

Steve Richert

On Documentation-Driven Development

By Steve Richert on April 21, 2014 in api, design, and documentation

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).

The README

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%?

APIs

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:

Velocity

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.

Consistency

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.

Transparency

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!

By Steve Richert on April 21, 2014 in api, design, and documentation

4 Comments

  1. Rob

    Rob April 22, 2014

    What tools are you using for writing api docs?

  2. Steve Richert

    Steve Richert April 22, 2014

    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. Hannes

    Hannes April 25, 2014

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

  4. Steve Richert

    Steve Richert April 25, 2014

    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.

Post a Comment

Contact Us

Find us on Google Maps
Collective Idea
44 East 8th Street, Suite 410
Holland, Michigan 49423 USA 42.790334-86.105251

Follow us on the Interwebs

We are currently available for medium and long term projects. Please get in touch if we can be of service.