The Impact Of Not Including A README File
Over the last week, I have looked at the code for four projects at Platform Eight. There was a common thread across the projects and that was a complete lack of documentation. This seems to be an ongoing problem across nearly all of the projects I have been involved in over the last year and it needs to stop.
Now I know that as developers and creators 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. Even small projects are much more than just code. This post isn’t a rant about a lack of functional documentation or schematics. Agile rightly attempts to limit this.
At a minimum, every project needs an up to date, relevant README file.
What Is A README File
A README file is a file written using Markdown syntax. It is used to convey some basic information about your project and how it works. 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.
The Difference Between A Good And Bad README File
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 on the reputation of 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 another developer takes over a project they want to be up and running with the code ASAP. They don’t want 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.
