README files


Imagine you’re joining a new software project, within your company, at a client or an Open Source project. You get the source code on your local machine, eager to get started right away, but then what? There are no instructions available. There is not a single text file explaining what this source code is doing. Also, no explanation about supported environments, what needs to be installed and so on.

I’ve been in this situation numerous times in the past, with clients I worked for but also with Open Source projects. Then usually my first contribution to the project is a fresh README file with information I could gather from just installing the project, reading the source code or from talking to other team members.

What usually goes into a README file is:

  • A brief and concise description, explaining the purpose of this project
  • Installation instructions including: supported operating systems, language runtimes, compilers, system packages, …
  • Start developing, as in what do I need to do to get started
  • How do I submit contributions
  • What’s the project’s license

When you create the file initially, it doesn’t have to be a 100% complete. It is a living document that gets enhanced over the time. But you might ask yourself how do you find out if what’s in the file is sufficient? There are two good ways to test it:

  • Have a new team member go through the instructions
  • Test it yourself after you didn’t work on the project for some time

Then, every time then something is unclear or does not work out of the box, change the paragraph or bullet point in the file so it becomes clearer and more descriptive. This is especially valuable for new team members, since they get accustomed to the project’s contribution process and they already added something helpful.

For me personally, before I got in touch with Open Source projects I was not really aware of README files and would rarely look at them. But since GitHub and GitLab started to show them by default for every project they host, my awareness definitely increased.

So, why should you add a README file?

Well, there are two reasons. For one, it’s the project’s business card. The better the business card looks like, the more likely people engage and contribute to the project. But also, and more important: it saves time. It saves time for each new contributor because they directly learn what they have to do to get started. With this time they have saved they can directly jump in and start to make good and valuable contributions.

About the author

By jan