Several years ago, I was teaching a class in St. Louis. Being in the city for the first time I wanted to take advantage of this trip to see “the arch”. One night after class I looked at my maps and planned my trip. I was successful in getting there and soon turned the car around to head back to my hotel. It was winter, so while it was not yet late, it had gotten dark. Soon I felt like I had driven too long and too far and feared I had taken the wrong route. I started to feel a little worried. Then I remembered that I had a GPS with me. This was the first trip that I had ever taken with a GPS. It was very basic, but I had added a waypoint for the hotel before I left home. I took the GPS out of my bag and my worries faded. Soon I was back at the hotel preparing for the next day’s class.
I imagine that you can relate to the feelings of being lost, confused and worried. Having tools to guide us through new adventures can make things easier and more enjoyable. Today it might be hard to imagine my experience because of the technology we have in our hands with our smart phones, but at the time the “struggle was real”.
How does this relate to README files?
What does all of that have to do with a README file? For some of you it may be hard to remember your technology life before the modern README file. For those of us in the grey hair club the struggle was real. Unfortunately, my experience is that while we have the tools and many best practices are well established, too many projects still do not use them.
When you start to work on a new project how do you get setup and productive? Over the years I’ve seen many ways this is done. Here are some of the most common:
• Scramble
• Developer’s setup guide
• Bug the team
• Mentor
• README
Too often, especially for internal projects, the process seems to be a mix of the first four approaches in my list. Usually you will at least get pointed to the source code repository (you are using one – right!). From here you get a copy of the code and compile it, or at least try to.
This is where the fun starts. You then need to look for the documentation that someone, long ago wrote on how to set everything up. But you soon find it either doesn’t exist or is so out of date that is hurts your progress more than it helps. Next you start to bug your co-workers. Each one has a different tip they remember, and this moves you forward, but at a slow pace. Slowly you work your way through the process. If you are lucky you find the one person on the team that actually knows everything, and that mentor, if they have enough time, leads you to the goal of finally being able to add value to the team.
There is a better way!
The README file should be the best friend of a new team member. It should contain the information that is needed to understand what the project is about and how to become a valuable, contributing member of the team.
The Open Source Software (OSS) world has established a good practice of including useful README files in many projects. In the OSS world anyone is welcome to join and work on project (this is a generally true statement that does have some exceptions and restrictions). People who join the project may do so from anywhere in the world and may work at all hours of the day and night. It is not feasible to have a mentor help each of these contributors get prepared to contribute. This has driven OSS to rely heavily on standardized documentation to direct new people.
What is the README file?
Logistically a README file is stored in the root of the project repository. It is written in Markdown syntax which allows for easy formatting. There are many good pages on the web that can help you learn the Markdown syntax – it’s all just a search away! Markdown is pretty easy and quite powerful, and you should be able to quickly figure out how to make an attractive and useful document.
When you create a new repository in GitHub you have the option of having a README file added. This is a very basic file, and in reality, it is useless except to remind you to add relevant content. Here is what you get when you choose to add a readme file:
################ Contents of README.md file ##################
readme-blog
This is a sample GitHub repository for my README file blog post.
######################################################
The initial version of this document only contains the repository name (readme-blog) and the description.
What Should You Include?
As noted above, a new developer will expect to find everything they need to become productive in the README file. This will likely be a little different for each project and organization. You can probably build out a template for use in your team. Below I reference examples from some OSS projects to give you a few ideas of what is important in your environment.
The following list contains some sections that you might consider including:
• Project description and purpose
• Pre-requisites
• Required tooling (IDEs, testing frameworks, languages, etc.)
• Suggested tooling (visual Git tools, IDE add-ins, etc.)
• Team standards (coding standards, test requirements, etc.)
• Project documentation
• Related projects
• Instructions to build the project
• Instructions to run automated tests (you have them – right!)
• Instructions to deploy the project locally for testing (you have automated deployment setup for dev, test and production environments – right!)
• Current CI/CD status (live links to statuses of automated builds and deployments)
If you are setting up an OSS project you might also want to consider adding sections for:
• Contribution guidelines
• Code of conduct
• License information
If you include all of this information the file might become rather large. To keep the README file manageable, you might want to create multiple files and link them together allowing the reader to dig deeper into the topics that they need when they need to. The OSS community has also established some common practices for this. You will often find separate files with the following names (they should be self-explanatory): CONTRIBUTING.md, CODE_OF_CONDUCT.md, and LICENSE.md.
If your project is large it is likely that you have different modules, or features, included in separate folders in your repository. This is another opportunity to add README files that are specific to that area of your code. It is common to have a hierarchy of README files spread across your folder structure. It is a good practice to link to each of these from the README found in the root of the project.
Final Thoughts
You might have noticed that I have consistently written README in all-caps. This is the standard and helps these files to standout when someone clones the repository and starts to review the contents. Beyond this, environments like GitHub will also recognize the README file in a repository and automatically display it to the user.
Software developers typically love to write code and hate to write documents. You will often hear people say things like “the code never lies” and “documents are always out of date”. I encourage you the consider the README file as a special case. Proper maintenance of this file will reduce the time it takes you to support the on-boarding of new team members. This will ultimately increase the speed at which your project can deliver value.
As a member of a team please take the time to make the journey better for others. Create, update and encourage others to use the README file in your project. Make sure that it is a valuable tool to help others become strong team members on your project!
A Few Examples to Review
I reviewed a few OSS repositories on GitHub and identified three that are substantially different and should give you some ideas of what you want to setup as the standard for your organization. You can browse through GitHub to find many more examples. Here are the links:
• DefinitelyTyped (https://github.com/definitelytyped/definitelytyped)
• Microsoft Azure Documentation (https://github.com/MicrosoftDocs/azure-docs)
• Tensorflow (https://github.com/tensorflow/tensorflow)
