If you’re anything like me, the first file you commit to a new project is the README.md. It provides a place to keep working notes, instructions to future developers and users, and most importantly, a place to plan before you jump into coding.
The README provides a first look at projects on Github and Bitbucket, so it often serves as an advertisement. A great README shows the value of a project and guides the user through their first experience using it. A bad one can turn people away entirely.
Before we dive in to what makes a great README, we’re going to take a brief detour into the origins of the file. If you’re not interested in the historical context, feel free to skip ahead.
History of README
The first README files date back to the 1970s, and early hacker lore marks the naming of the file as coming from Alice In Wonderland. Just like the bottles in Wonderland had simple, self-describing labels like “Eat Me” and “Drink Me”, readers will find it hard to misinterpret what to do with a README file.
The all-capitalized name is not just for impact, however. When sorting ASCII and Unicode, capital letters come before lower-case, meaning that README will most often appear at the top of lists of files.
Today, most README files are created in Markdown format (“README.md”), but they’ve historically taken many different file formats:
- README.TXT
- READ.ME
- README.1ST
- README
Elements of a great README
You should always include a few core things in your README file, no matter how big or small your repository.
Installation & Usage
When evaluating a new tool, I often try to figure out how much work I’ll have to do in order to use it. A solid set of installation and usage instructions, complete with copy-and-paste commands, will help your most technical users quickly jump in and get started. A very comprehensive example of a getting started section is the Facebook-owned tool, Create React App.
When looking at the README.md, their “Quick Overview” section is located after a very brief value statement at the top of the README. This positioning is critical, as users spend about 65% of their time looking at the top 40% of a document, according to Nielson Norman Group.
One of the most eye-catching elements to developers is the code block. Since I can see exactly what’s needed to get started, the barrier to entry is very low. I can immediately pop open my CLI, copy a few commands, and give it a shot.
Finally, when viewing a README on the web, we can take advantage of GIFs and videos showing the tool being used. This sets expectations for users, and helps them understand the output of the tool.
Value Statement
A value statement sells the user on why they should use the tool, as briefly as possible. Create React App’s does it in seven words, which is exceptional. Users who are looking at the README likely don’t need the concepts of React or build configuration explained, so the author can speed along past explanations on to why the reader would want to use this.
Not all tools can have such beautifully self-describing names, however. Another repository with a concise value statement is the Python library Beautiful Soup.
Beautiful Soup is a Python library for pulling data out of HTML and XML files. It works with your favorite parser to provide idiomatic ways of navigating, searching, and modifying the parse tree. It commonly saves programmers hours or days of work.
Even the shortest of attention spans will be able to finish these three short sentences. It starts with a bare bones description of what Beautiful Soup does, and finishes with a concrete promise to the user on saving time.
Final Notes
Keep these two elements in mind next time you’re starting a new project! The README can contain much, much more than just the things we’ve described here, but the most impactful elements should always come first.
