Recently we talked about how important communication is in the life of a project. In software engineering, a big part of the communication is delivered through documentation. And on the field, nothing beats a good README.
So.
What Makes a Good README?
In almost no particular order
It is up to Date
This might be the most important rule.
A README is a reference. It’s gospel truth. And the problem is that being so, it will be followed religiously, not being questioned (at least for the first hour of debugging).
An outdated document is by essence an erroneous one. So in the same manner it wouldn’t make sense to put a wrong command in a README, you certainly don’t want it to make reference to an old deployment tool.
Not surprisingly, this is also the hardest rule to follow. As a project evolves, we usually only add to the file, when it should be just as important to remove, edit and even sometimes rewrite it entirely.
It is Concise
Or at least it feels that way (see next rule).
Make your headers precise, clear, and fat-free.
Make a Table of Contents of them, at the top. This will not only help the reader to navigate, it will also help you structure your document.
Short sentences, lists, short paragraphs, line breaks. Go to the point, but don’t miss it
Yet, it is Thorough
When in doubt, break the previous rule rather than excluding a tiny detail that might cost you or a colleague three hours.
You’re not running out of space, and if the information is valuable, the time invested in reading it will be worth it.
If you feel it is running too long, a good practice I have seen is to separate the README files so that they only relate to the context of the files they deal with. For instance, create one in your db directory and explain how those particular migrations should be run. In this case, make a note of it somewhere in the main README, or even list and link to them.
It Puts Itself in the Reader’s Shoes
A regular issue I have with READMEs is that they have been written by and for a developer already very familiar with the project. It’s a natural thing and I don’t want to blame people for it, when you have been working on an app for several weeks or months, to feel that some details can be overlooked or that some settings are obvious.
When you write, try to put yourself in the shoes of a complete newbie to the project, or maybe even a newbie to the profession. State the obvious, write full commands, repeat some information in their context.
Another approach is to think of you, 6 months from now, at 3 am, with the beginning of a cold, trying to deploy your app after an unfortunate event. You will thank yourself for such a good documentation.
Just like a picture is worth a thousand words, an example is worth quite a few lines of explanation. So explain and describe, and add lots of examples, in their context, to make sure everything is clear.
It is Completely Self-Contained
You can’t know how, where and when your document will be needed, and suggesting someone ask a third party for more details or a file or a data sample won’t work.
Let’s say you are still trying to rebuild after the aforementioned unfortunate event. It is now 4am, and the cold is gaining on you. And there, you read something like to get the needed sample data, ask Steve. Well, Steve won’t be happy to receive your call, not only because it’s the middle of the night, but also because he left the company 2 years ago (and someone broke the first rule).
If the data is too large or too sensitive to sit inside the README, put it elsewhere and link to it. It’s not like the internet is running out of space.
It is Easy on the Eyes
It is easy to make a README nice to look at. The Markdown/GitHub combo ensure your flat text file, while staying readable as is, can be clear, and pretty.
Use different levels of headers, strong and emphasis, inline code blocks, and links
This can make all the difference.
It is Only what the Reader Makes of It
Beauty is in the eye of the beholder.
The best README will only be as good as what is made of it. The reader also shares a large part of the responsibility for the quality. When you use a README (and if you get to write some, you will certainly read some others), don’t skim, don’t skip, don’t be lazy. The writer of a README is in a good position to know what the crucial points are, so try not to skip over anything.
Conclusion
There are many forms of documentation. Each has its purpose. From the one line comments inside the code, to the fully automated reference, to the complete knowledge base. I think READMEs have the best time invested / efficiency ratio.
At reInteractive, we use templates to help us meet these goals. They are publicly available on GitHub, should you need a nudge in the right direction: reInteractive Default ReadMe.
What’s your secret sauce for writing a good README?
