The README is a solution to a basic computing problem:
You find a directory full of files. Maybe it's a directory on your computer, or perhaps on a corporate internal drive, or part of an open source project, or maybe even some files generated by an application, open source or otherwise. The problem is: you don't know what those files are.
The README is a file, with a name like README.txt, or perhaps README.md or somesuch, which answers the basic question:
What are these files?
Or, in more colloquial terms:
What the f*** are these files?
A README doesn't have to contain a whole lot of stuff. Even the most minimal README is better than no README at all. Some suggestions are:
If the files already have good documentation somewhere else, the README can give a pointer to that somewhere else – but a minimal self-contained description is still desirable, because sometimes the somewhere-else accidentally disappears, or moves to a new unknown location.
It's also strongly recommended to add a date and the writer's name (i.e. your name, when you're writing it). Like all documentation, README's can get out of date. A date and name doesn't tell the reader how good the README is as a description, but it does tell him or her that this README was a best effort at a description, as written by that person, at that date. This helps the reader to make a snap judgement about how reliable and up-to-date the README is. And possibly he or she can make some effort to contact the README writer, and ask for clarification, or ask if the README is still accurate and up-to-date.
There is just one valid excuse for not including a README in a directory, which is that there is a README in some higher-level directory, which adequately explains the contents of all the enclosed sub-directories.
So if the top-level README doesn't adequately describe the contents of all the sub-directories, write README's for the sub-directories.
Following those preliminary discussion points, here is my manifesto:
You might think that you already know about README's – you've read them and you've written them, and you know that all GitHub projects should have a top-level README.
But, I bet at least some of the following apply to you:
README's are really great for files in directories. But much modern data is in other forms, like Registries, and Corporate Relational Databases, and other kinds of databases.
These alternative data structures also need README's, even though it's less obvious where to put them. Maybe your SQL database has a special place to put descriptions of objects. If it doesn't, consider making a special README table, which has columns to identify all the types of named object (like tables, and columns, and stored procedures), and include a "description" column to contain the descriptive text for each object. The single most important rule here is that whatever contains the README information must contain the letters "README" in its name, because that is the universal convention for making README information easy to find for the person looking at the data being described, who does not know anything, a priori, about how that data is structured.
If README's are such a good idea, why doesn't everything already have README's?
For the answer to that question, read my next article The Psychology of Not Documenting Stuff.
