In my job I spend a lot of time reading other people’s GitHub accounts — poking through their code and sometimes installing it to try out. Many README files are too sparse to be useful to me in that. As a result I have to spend time on my own, figuring out what’s going on in the code, or else abandon the effort. If I abandon the effort, I then have to fight the temptation to assume the programmer is lazy or the code isn’t finished. That outcome is not ideal if my reason for reading the code was to evaluate the programmer’s skill and attention to detail.
A README isn’t just designed for other users encountering your code for the first time; it will also be useful to you after you’ve been away from the project for a while — if you’re like most people, you’ll have forgotten a lot about it by then.
Below are the things I look for in a repository README file.
-
What the project does.
Even if there isn’t anything else in the README itself, a link to any separate documentation site can go here, as can a statement of any software license covering the code.
-
How to install it, including dependencies.
Be aware that you may be relying on dependencies that were put in place long ago, and that you’ve forgotten about. The user needs to know about them, though. One way you can make sure you have all dependencies accounted for is to write a script to populate a container for tools such as Vagrant or Docker. You should also mention what operating systems the project has been tested on, because that is a kind of dependency, too.
-
How to run the code.
You should illustrate, even if it is obvious to you. If there are separate compilation or linking steps, show them; if your code is meant to be run in a REPL or browser console, say so here.
This is also the place to name the main sorts of functionality provided by the project, and to illustrate them. Remember, after time passes, you may have trouble remembering what you’ve actually built here.
-
Discussion and references.
If the project is meant to display your skills, in the manner of a portfolio, it would be nice to hear about design decisions, surprises you encountered, and anything of interest you learned while doing the project. If there are external sources that were useful to you, cite them here. If there are people to thank, you might do that here, too.
-
Work still to be done, known bugs, future plans.
Not all of this has to go into one huge README file. You can put separate sections into separate files — if there are two or more of them, you may like to place them in a directory called doc or something similarly suggestive. Nor does a README have to be exhaustive — but it should address the several headings I’ve listed above.
[end]
Comments are enabled.