I’m at Write the Docs today in Budapest and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Thomas started the sessions after lunch. He’s a JavaScript Engineer at the BBC. In 2011, after returning from a trip to Iceland, Thomas attended a conference in Paris where someone covered research illustrating how people learn more effectively from talking about something than reading about it. It prompted him to think about whether we should be talking about things more than relying upon static documentation.
He was working at a startup that grew from 1 to 5 and more projects. They needed a better way to document what they were doing. As he put it, so much time is put in to writing code that powers useful software. We want to share our work and findings. Documentation, in part, becomes how that end result is communicated to others.
At the startup they moved toward README-driven development for a few reasons. It’s the default file that GitHub displays, for one. A README is a simple and fast piece of content to write. It can also be written and then transformed in to any number of formats. The goal is to sum up what software does in a few sentences.
At any point you can use any number of tools to edit a README alongside the versioned code. You’re not pushing people to a separate website to learn about the software. Through the inclusion of examples and effective content you can help people right within your source files.
With intro information contained in a README you can tell at a glance the limits of your software. Setting shallow limits for your README helps ensure users can understand your software quickly.
Part of what’s key about README driven development is that it’s about ideas and new projects just as much as it is about existing work. You can lay the groundwork in your README before you write any code. It can create crystal clear guidelines for developers and allow you to gather feedback before shipping your code. By writing the README you are sketching your idea of what will be produced. Doing all that work ahead of time allows you to iterate faster.
This all helps in detecting complexity. As your README becomes more complicated it means you’re maybe trying to do too much within one project. It can be a helpful marker to when you need to break things in to their respective pieces.
Focusing on the README can even help in pull requests, bug repots, and other aspects of development. Being detailed there focuses on the intention of your code rather than the code in isolation. That can prompt discussion about whether the intention is ideal regardless of the code attached.
Ultimately focusing on the README first gives users a single entry point to your project. It emphasizes the correct things, makes dialogue easier, and gets you to top-quality code faster.