What Every Developer Must Know About READMEs

Written .

Photo by Art Lasovsky on Unsplash .

For Open Source projects on github.com a README file is mandatory. But what about your company’s internal and proprietary project? In this post I will tell you why having a README file is essential for ANY project and what it should (and should not) contain.

TL;DR Every project should have a README. No exceptions! Consider your audience and write what you think is most relevant to them.

Why Should You Care?

My first public project dates way back to 1992. It was a numerical simulation of planetary movements written in Turbo Pascal. Back then, there was only rudimentary version control and no public shared repositories. Basically, I had to send floppy disks to anyone who (a) learned about me and (b) cared enough to ask for it.

The popular term for this kind of thing was “public domain” software which you might call a predecessor to what is open source today. A few years ago I wanted to upload this software to GitHub and make it available to anyone who cares (admittedly, I didn’t think it would be many people, but still).

And guess what? I didn’t know whether you could still run it on a modern computer. In fact, I couldn’t even remember how I ran it back then. It was as if someone had sent me the program source code and asked me to figure it out all on my own without help. After figuring it out I have uploaded the code with instructions for running it on a contemporary system.

You might wonder if this problem is really common? Do people these days care about software written long ago? Aside from Abandonware the very same applies in very common, everyday situations:

  • You onboard a new developer to your company.
  • You revisit on older project – where “older” may refer to anything you did longer than a few days ago.
  • You share a project with a supplier or subcontractor.

These are audiences for whom you write a README file!

So how do you know which project will be useful? Simply put, you won’t. Your five-minute ten-line hack may become the backbone of the internet (like this simple library which broke thousands of dependencies when it was removed) or your mega-project with one million lines of code will fade into obscurity. You won’t know in advance. And this is why it never hurts to put a README in EVERY project that is not deleted when you go home in the evening.

What Should You Write?

There are plenty of guides with advice about writing a README when you want to host your Open Source project on GitHub, see e.g. this template and this post. But not all projects are like that, like the projects mentioned above. In that case I have a fundamental rule:

Imagine your intended audience. If they are checking out the project, what do they need to know? Write just enough for their next step.

This is the starting point. Your README is like a product targeted at an audience. Treat it like that! I don’t advocate doing A/B testing, getting a professional editor for proofreading and a designer for visualizations. Instead, I strongly advise you to think about who it is that you are writing for:

  • Is it a developer who wants to run the code?
  • Is it a developer who wants to work on the code?
  • Is it a user who wants to use what the code does?

In each of these cases they need different information. Just by thinking about your audience and considering what they might be intending to do you are already way ahead of most READMEs you can find on the internet.

If you target multiple audiences (e.g., developers wanting to run the code and those who want to contribute) it is imperative to point out who should be reading what, e.g., “for contributors please read the last section at the bottom”.

In general, it is also a good idea to write explicitly who a project is intended for, e.g., “this project is a debugging tool intended for Javascript developers working with Vue”.

What Should You NOT Write?

A README shall not replace other documentation. If the project needs a complicated setup then the README would be the place to point readers to where they can find out more (like a dedicated file INSTALL.md). If the project has a user manual then tell the reader how to find that manual, NOT what is in there.

When Should You Write It?

The best time to write it is when the project is created. At that point it doesn’t need to contain much.

The key is to regularly update it whenever it becomes outdated. A good habit is to review it with every pull request and see whether it is still up-to-date. And then amend or correct it as needed.

How Should You Write It?

For projects hosted on GitHub the preferred syntax is markdown. For other projects I also use markdown since it can both be rendered well in a web browser with tools and is human-readable. Most IDEs and code editors offer a “live preview” of markdown which makes it very easy to use.

Examples

Here are a couple of examples of READMEs and my personal take on them:

Corona Warn App for iOS
This is an excellent example of a README! The overall documentation of the project is exemplary and we find exactly the information we need to take the next steps, how to locate further information etc. It is also quite short and well-structured, so I am not overwhelmed when looking for something. Notice the excellent introductory paragraph that tells exactly what the project is about without going into too much detail or being too verbose.
xcpretty
This is a popular project, but I do not like the README that much. To begin with, it starts off with a concise intro line. If you are an iOS developer you’ll know right away what is xcodebuild, but if you are not you’ll wonder what technology this project is actually about. A short remark that this project is ONLY for iOS developers using command line tools would go a long way here.
Further down on the page you see two animations with output, but for the second case I still can’t figure out how the output relates to specific features of the tool. It contains superfluous editing and is quite confusing. Last but not least, the project has not been touched for five years. If you go through the issues discussion on GitHub you’ll learn why, but it would have been much better if (as the last thing the developers did) there was a note in the README telling me about the project status and why it won’t be updated anymore.
jekyll-category-pages
This is my own project. In general, this README is not just a README, but rather the entire project documentation. As such, I feel it is a little too long and verbose. It also combines instructions for users and contributors. In the beginning I say what it does, but don’t mention that it is a plugin for the jekyll static website generator. Then I list the benefits which is in my opinion the right place to show off the features.
So far there was no one who failed to understand how to use the project, so as a documentation it seems to be doing fine. On the other I don’t believe I did a good job keeping the README and documentation separate.

Summary

Every project needs a README. Think of the person checking out the project. What does she want and need to know to take the next step? Write just that. Neither write too long or verbose nor leave important information out.