< Home

The 10 commandments (guidelines) of a README

This article is less about attracting people to use an open-source project. Or having the most attractive README. But more about trying to get people up and running on a production app. And contributing work as soon as possible. The act of increasing “productivity” if you like.

I am pretty sure everyone reading this will at some point have landed on a project on a Monday morning. Found that they don’t know anything about the project. The README is bare. It outlines how to get the application up and running; it takes you 20 minutes to get the app up and running. You then crack your knuckles and settle down to get writing code. You run into the fact that you have no idea what the project is or how it works. You switch over to slack, ping an individual or a channel to gather some more information. The person who was working on it last can’t quite remember either. Before long, you have dragged other people into helping you. At which point, neither of you are doing anything productive.

This is where the importance of a detailed README becomes clear.

Below, I outline my ten commandments of a README. By following these, you will see a reduction in trivial/time-consuming questions.

1. Include the project name and a brief “business” description.

Start by outlining the project name and give a brief description of what the app does. By providing a description, it will allow an individual to start to comprehend what the application does from a high level. If your app deals with buying and selling motorbikes, look to describe how this happens. As an individual looking at the source code, this will help to understand how the data model ties to the domain. As opposed to, here is the source code, try and figure out what it does.

I would also urge you to put links to production environments at this stage. An individual is then able to go and have a click around and work out how the site flows.

2. Detail the technical stack

It is very easy for developers to say “Hey, it’s clear it’s a rails app.” I know this happens because I have been guilty of this response myself. The smaller pieces of the stack often get neglected and overlooked. These are as important as the main stack.

You should look to outline that the app uses Redis for X, ElasticSearch for Y and Webpack for Z.

Describing these pieces of the technical stack helps the individual. By allowing them to see how the tech ties together.

3. Detail 3rd parties

Third parties are becoming more and more commonplace. It could be something as simple as integrating with a CRM or a stock management system. But, I promise you, if your app does anything significant you will have to integrate with a 3rd party at some point.

With this in mind, it is important to outline which 3rd parties you integrate with, if any. You should point people in the direction of setting up a sandbox account (if possible.) You should also look to outline what configuration steps to take. Getting the development environment in line with the production environment is very important.

4. Detail how to get the app running

I mean this goes without saying, in fact, if you don’t have this, why do you even have a README?

5. Hosting

It may not seem important to describe the hosting infrastructure from the outset. You’re probably thinking “Why does anybody need to know about hosting at this point?” Well, potentially not. But, it allows the individual to have full autonomy. It will enable them to make the most informed decisions. An example of this would be, say you were hosting on AWS, and the task was to add ElasticSearch. Knowing that the app is hosted on AWS would be beneficial. An individual could choose to use Elasticache or a 3rd party. Both of which would need different code additions.

6. Demo/QA environments

Outline demo/QA environments. Simple but necessary. It allows the individual to make debug in a production like environment. It allows them to do this without the fear of causing detrimental effects. It also alleviates the tedious question of “What is the demo URL?”

7. Deployment

Outline your deployment process. If you practice continuous deployment, describe the process of how you execute it, do you use flags or not? If so, who can see those flags? Who can alter those flags? Try to answer all the questions that would likely dictate development decisions.

8. Creating useful records

Creating useful records is the single most important thing to do. Getting data into the app in the expected format is great. It allows the individual to fathom how the data model comes together. Creating these records not only allows your application to be working locally. It also allows the developer to tie records and 3rd party service together. Understanding the data is a big road block for large applications.

If you are using a 3rd party, you should walk through how to create these records. Both on 3rd party software (if required) but also on the app. It will help ease the potential for a tedious question of “what does column X relate to?”

9. Detail caveats

As with all software development, there is going to be caveats it’s the nature of this industry. i.e. X works this way because Y happened. You should look to outline any of these as best you can. It’s not always apparent to an individual unfamiliar with the app.

Any caveats will allow the individual to know these in advance of any problems. Resulting in less time to debug something that is already a known problem.

I have heard “I remember it being done that way for some reason” too many times. Write it down so everyone is aware and knowledge is not forgotten.

10. Be clear and assume no knowledge

Finally, be clear and in-depth. You should assume no knowledge of the project is known. It is easy to get wrapped up in the project and think “I don’t need to explain that, it is evident from the code.” For an individual who is new to the project and trying to find their way around this is not the case. Things that came to your head but feel obvious go ahead and write them down in the README.

Conclusion

These “commandments” are more a set of guidelines. I understand that not all projects will need to cover all the points. For example, if you have a static site, seeds may not apply to you, in which case feel free to ignore. You should use this guide to think in the back of your mind “Should I document this somewhere?”

Another thing to note is that not all this information is available straight of the bat. With that in mind. I would encourage you to consider your README as important as the code.

And one final note. If you are as clear as you can be in your README, I guarantee you it will save you a whole lot of time and headache. When an individual comes to use your application, they will have a lot of the domain knowledge in front of them.