Include A README

08 October 2019

Photo: Brennan Angel

Over the last week, I have looked at the code for 4 projects. Each of these is for clients for my new consultancy, Platform Eight (more on that another time). There is a common thread I have seen across the projects and that is a complete lack of documentation.

Now I know that as developers we hate documentation and I get that. The dream of writing code that is so prose-like that no documentation is required is still just a dream. This post isn’t a rant about a lack of functional documentation or schematics. Agile rightly attempts to limit this.

What every project does need though is an up to date, relevant README

A README file is a file written using Markdown syntax. It is used to convey some basic information about your project. Details such as how to clone it, required software or libraries and how to build and get the project running. The README is usually found in the root of the project folder. Git-based source control systems such as GitHub use this content. They display it when you land on the projects hosting page.

Now stop and think about how you mentally feel when searching for projects on GitHub. Do you trust the projects that have no details on their page? Or do you find yourself more trusting of the pages with lots of helpful details and screenshots?

Private, commercial, projects are no different. Git allows me to see who has worked on a project. Their reputation to me is influenced in the same way as you are influenced when landing on a GitHub project. The impact of a reputation for software teams and dev houses is even greater. When being paid to start a project with a view to handing it back, the lack of a README or any basic project document is damaging. I would advise any client to demand this document in any agreed contract or agreement or withhold payment until it is produced.

Why? Well, there are a couple of trains of thought here. The first is developer productivity. If a developer takes over a project they want to be up and running with the code ASAP. They do not need to spend their time figuring out how they need to configure their machine. What version of the stack should they be running? Which libraries and versions need to be installed? Some frameworks make this a trivial matter. But some allow you to set up projects and environments in various ways. Again this matters if you transfer a project between developers or teams and you are paying a day rate. You are effectively doubling your costs. The other thought is that if the developer(s) can not be professional enough to add a README then what state is the code in? That might seem a harsh comment and is not always the case but it carries merit.

As always you might want to think of it from an investment point of view as well. If you have to go through a Due Diligence process with no basic documentation then you will need to defend that.

Here is a great template from GitHub. If you need to, go and copy it and fill in the blanks. Don’t be the developer or team that tries to hide or use your project knowledge for financial or reputational gain. It just makes you look bad.

If you have thoughts around this subject please contact me via twitter or email.