Why Keeping Your README Updated is Important

By Jonathan Wang

When I joined Niedziela Solutions, there were multiple repositories I had to clone and familiar myself with. I’ve had a couple realizations about setting up code repositories since I’ve been working here.

PERSONAL REFLECTION OF README

Cloning a code base and following the steps of a README should be easy to digest and follow along. And for the most part, I was able to easily follow the directions of the README until something wasn’t working. I made sure I installed all the necessary software pieces in place and installed all dependencies at versions that matched what the code base was using.

As it usually goes, the accuracy of a README is usually tested by a new hire and it becomes their responsibility to document and update any new or missing steps to have the code base running locally. This is important so that any future employee setting up a code base on their local device can do so seamlessly, whether it’s a new employee or a current one setting up a new device. Updating and checking the accuracy of the README is usually my first PR (pull-request) when starting any new project. My experience was sometimes a bit different than usual because I was following the instructions of the README on a M1 Macbook for projects that have never had someone use an M1 device. Following the README steps for M1 wasn’t super straight forward because there were several additional updates and other complications that I came across when trying to follow the README. This process required some extra support from the internet because not everything simply worked by just plugging and chugging.

So, from that experience, I can see how if the README isn’t current and regularly checked, it would make it harder for the next person to setup.

DOCUMENT README’S ASAP

Sometimes on the job I will have to context switch and go from one clients codebase to the next. When switching over, I’ll try and run the application on my computer and so many times something will happen that prevents it. This is due to one of many reasons such as software tools needing to be upgraded, local configuration needing to be updated, or dependencies in a repository needing to be updated. The reality is that all of this is very normal. We’re constantly trying to stay up to date with our software tools and dependencies that require us to upgrade.

There are many reasons why keeping documentation fresh and up to date is important, such as:

• Detailing errors that might occur in setup and how to workaround them so someone else doesn’t have to figure that out.
• Revising and adding clarity to previous versions of documentation so it doesn’t confuse new members.
• Reducing time spent digging around or repeating unnecessary tasks

These are just a few reasons why documenting README’s as soon as one can is necessary and why it’s important to keep every vital piece of developer information up to date. I know most developers dread documentation and find it tedious but it’s a part of the process for a good reason and will go a long way for a few of the reasons I listed above.

OVERALL

Overall, it is important to keep the README up to date. Make sure when any software tools are changed/upgraded, go give the README a look to see if everything still applies and actually works. It’s best to document right away when important information is fresh and to be thorough.