Why Keeping Your README Updated is Important
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, 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.
Expo + React Native as a Beginner
12/02/2021 - Jonathan Wang
If you told me that in the first 6 months of my 1st development job that I would be working with mobile development, I would have thought there was no way possible since I had little to no knowledge of...
First Year in Review
10/25/2021 - Sarah Sunday
It has been a little over a year since I officially started the business. Which means it’s time for a retrospective! This is going to be all over the place, which is where I’m at mentally right now. It’s not...