README driven development

I recently read an article by Tom Preston-Werner about how to solve the undocumented project problem—how do you promote a project when no one knows what it does? After I read it, I saw this article and its same solution everywhere. That solution is README Driven Development (RDD).

In open source and innersource projects, like the ones that you find on GitHub, GitLab, and Bitbucket, the README document is the project’s welcome page. It’s the first thing people see when they search for a project. README documents describe what the project is, how you use it, and how you can add to it. If you want your project to be successful, your README document must give a good first impression.

In RDD, when you start a new project, you start with the README file. This makes you plan out your project before you start writing any code. By creating the README first, you have to think about why you started the project, how you use it, and how others can support it. It streamlines your project from the beginning. RDD also means your project starts with a solid documentation base. Rather than creating your documentation after the fact, you start with a document that evolves as the project evolves. That’s much easier than trying to remember every implementation detail after you’ve pushed the finished project.

The following diagram shows the general approach to RDD.

README Driven Development workflow

In this article, I discuss how RDD compares to other "driven development" strategies, its pros and cons, and my own experience with it.

The historical context of README Driven Development

The software development world has seen many "driven development" strategies. Some examples are Test Driven Development (TDD), Design or Document Driven Development (DDD), and Bug Driven Development (BDD). They describe a mindset that software developers adopt to create good products. Often, they stress the importance of one component of the development cycle, like test suites or bug catches. This component becomes the driving force behind the whole endeavor. These kinds of software development strategies have been around for ages. I first read about one of them—Test Driven Development—in Robert Martin’s Clean Code: A Handbook of Agile Software Craftsmanship. Since then, I’ve seen all kinds of variations.

How does RDD fit into this group of development strategies? Rather than tests or bugs, RDD focuses on a project’s documentation. Specifically, it applies to open source or innersource projects that have their documentation as their landing page for new users. RDD, like the types of projects it serves, leaves room for flexibility. RDD starts with the documentation—the README—and it lets it evolve as the project evolves. In that way, it fits well with methodologies from other "driven development" strategies, like Agile.

Pros and cons of README Driven Development

RDD has many perks, including:

• It improves your project plan

  If you start with the README before you write a line of code, you must think hard about how your project works. A README covers what your project does and how to run it. If you already have a plan for these, you have a roadmap for how to structure the entire project. As a result, you create a coherent codebase that’s quick to learn and easy to extend.

• It makes it easy for others to contribute

  A clear README opens the door for other developers to add to your project. The first step to contributing to any project is to learn the codebase. Only when a developer understands how the project’s pieces fit together can they suggest improvements. If you want to attract more contributors, then you need to cut down the required study time. This is where a well-written README helps. Your README documentation describes how your project works. If your README describes the project in plain language, then others can see how and where to contribute without digging through the raw code.

• It keeps the documentation up to date

  It’s harder to write documentation for a finished project than to update documentation as a project grows. If you start your project with a well-written README document, then you can update it along the way. Otherwise, you have to remember all the project’s details hours, or sometimes days, after you wrote the code. Often, projects end up with no documentation, at all. RDD guarantees your project starts with a solid, documented foundation.

RDD, though, has its drawbacks. With RDD, you’re writing about what you want to build, rather than just building it. You hold yourself back—you have to write the README first. It’s a practice in delayed gratification. Sometimes, that delay doesn’t seem worth it. This post by LoneStar Agile backs this up when it says that RDD may not be suitable for projects that change quickly. If you manage a small or volatile project, you might think that RDD adds more burden for little benefit.

This is, of course, a serious issue. But it can be overcome with practice and training. Developers learn that putting their ideas in words means they backtrack less during development. They also learn that the coding experience is smoother when you have a rough plan laid out for you. And everyone else in the development cycle benefits from clear documentation.

My README Driven Development experience

After I read about RDD, I thought I’d try it out for a new work project. I wanted to create a repository of Databricks notebooks to help less technical users read and write data in their environment. Before writing a line of code, I started with the README. It was much harder than I expected. As I wrote about and developed these great ideas, I wanted to dive straight into them. Instead, I held off. I’m glad that I did. Because I started with the documentation, the project’s goal was easier to define. At one point, I scrapped the whole thing and started over because I realized that I wasn’t solving the original problem. I needed to pivot, and it’s much easier to pivot when you haven’t already wasted time to develop the code.

My RDD experiment had another benefit. It gave me an easier entry point into the project. When you have a big project in mind, it’s hard to know where to start. Which script do you start with? How do you structure the project’s folders? Is this one package or should I split it into many? With a README, you know exactly where to start: the README. That made it much easier to focus and get started.

Conclusion

To reiterate, the idea behind README driven development is to write the README first. Write it before you write a single line of code. This way you can plan your project better, open your project up to more contributors, and be confident that your project already has a great foundation in its documentation.

If you’re interested in learning more, check out these resources:

• See this curated list of projects with great README documents for inspiration.

• Get started with your own README documents with this README template.

• Use specialized tools to create your README documents, like readme.so.