For the first couple years of my analytics career, documentation was something I took for granted. It wasn’t until I started working at a startup that I realized just how important documentation was. The same analysis was done over and over again with slight variation in methodology because there was very little knowledge and insights passed down from prior attempts. As you can imagine, this wastes a lot of time and causes a lot of confusion for all parties involved.
A well-written README is the perfect answer to this. It gives the audience a clear and concise idea of what was done, how, and what the results were. For fellow developers reading the document, it helps them understand if the project is something they would like to reuse without having to comb through the actual code. For future employers, it showcases your work, knowledge and thought process all in one place. For your future self, it serves as a reminder on what was done so you don’t have to spend more than 5 minutes trying to figure it all out again.
This article will go through an introduction to READMEs, best practices, and some useful templates. Consider it a README of READMEs, if you will.
What is a README?
According to Wikipedia:
A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called Read Me, READ.ME, README.TXT, README.md (for a text file using markdown markup), README.1ST — or simply README
In other words, a README is a one stop shop introduction to your project… a sort of first impression if you will.
A good README will answer the following questions in a clear and concise manner:
- What is the purpose of the project?
- What are the prerequisites if someone wanted to use the code/software? (ex: is Python required? If so, which version?)
- How would one install it?
- How would one use the project once installed?
Best Practices:
Purpose of Project
The introduction should be short and to the point. scottydocs@GitHub suggests having two or three sentences that describes the software, what it does, and the intended audience.
Example Template: Project name is a <utility/tool/feature> that allows <insert_target_audience> to do <action/task_it_does>. Additional line of information about what the project does.
Prerequisites Checklist
Include a prerequisite checklist for readers so they don’t have to go through the whole package only to find they can’t use it.
Below are some common things to include:
- You have installed the latest version of
<coding_language/dependency/requirement_1> - You have a
<Windows/Linux/Mac>machine. State which OS is supported/which is not. - You have read
<guide/link/documentation_related_to_project>.
Installation Instructions
The installation instructions should be as copy and paste for the user as possible.
Feel free to include external links if the instructions are already standard practice or written out in detail elsewhere. There is no need to reinvent the wheel. Just remember to include notes on anything that might diverge from the link provided.
Usage
This is probably the most important part of your README. This shows the reader what is possible with your code/software. Include as many use cases as possible. This would also be a good place to include any common bugs or caveats.
Be sure to shout-out contributors!!
Conclusion
The key to a great README is simplicity. Most people look for open source codes to save time, not the opposite. Consider your three main audiences:
Fellow developers: They want to make a quick decision on whether or not your code works for their specific needs before they invest time into actually adopting it.
Potential employers: A good README can tell a lot about a person’s work style. Future employers can not only tell your technical abilities but also your ability to concisely explain what you did to a wide range of audiences.
Future you: Your README will jog your memory so you don’t have to reinvent your own wheel.
Think of a README like a first date. It is the first impression, the face of your project. You want to introduce your project but leave the trauma for at least the tenth date (actual code).
Examples of great READMEs
The following READMEs all share the common trait of having a clear and concise project description, easy to follow installation steps and great use of visuals.
Resources
- Scotty’s GitHub: https://github.com/scottydocs/README-template.md
- Dan’s GitHub (a curated list of awesome READMEs): https://github.com/matiassingers/awesome-readme
- Jackson Zhou’s Medium Article on READMEs: https://medium.com/@jacksonz666/readme-best-practices-7c9ad6c2303
