The Importance of README.md Files
Hi there, my name’s Matt. I’d like to throw out there that this is my first blog post ever and I hope that it will be the first of many. This article will be about a habit I find absolutely necessary when you begin learning to code. Yep, I’m talking about the glory that is READMEs.
At the time of writing this article, I am attending Flatiron’s software engineering program. Throughout the rigorous first few weeks of learning and retaining as much knowledge as I can, I’ve learned both good and bad habits through the experience thus far. Being a newcomer to code, it is incredibly humbling learning a new programming language and going through someone else’s code but not knowing anything. This is something that you will get accustomed to. There will be revelations you will encounter throughout your journey and it would be ideal to internalize all those revelations. One of the first habits I discovered to be crucial to learning code is the importance of README.md files. Currently writing this I am on my final day of working on my Mod1 Project and looking back, it wouldn’t have been possible without all the easily accessible documentation available for all the Ruby gems my partner and I have used throughout this project.
So what exactly is a README and why should you read it? Well to stay on the theme of READMEs being important, here’s a link to it, as well as what I’ve learned it to be. It is a plain text file that contains information about a project. It is used mainly to write basic documentation inside a project directory to describe its usage and setup instructions. Popular repository providers such as Github, use READMEs as a file descriptor. The .md stands for markdown and is a lightweight language with plain-text-formatting syntax. It is essentially the standard for writing READMEs. Working through my first coding project written in Ruby, my partner and I have had to incorporate multiple gems to increase the functionality of our CLI(command line interface) app. This includes gems such as tty-prompt and rake. Both were abstract ideas when I first stumbled upon them but I knew we needed to implement that functionality into our project. Needless to say, it was intimidating at first figuring out exactly what to do with the gem but as I’ve learned from working on past labs, the gem’s directory READMEs would save the day. The file contained all information regarding basic setup using require and how to properly write methods making use of the gems functions.
Before programming, I was the type of person to start working before I read everything a task needs to be complete and skim through notes whilst believing I am able to grasp a concept and figure out with the bare minimum(shoutout to my project partner Anthony Rubbo for dealing with me jumping the gun on our project and trying to bite off more than we could chew). So I relate to everyone that feels as if you can skim through a repo or programming concept and think you can figure it out on your own. In reality, at least for me, there is no shortcut to learning how to program. I’ve learned to accept that learning to program is a constant cycle of being in the unknown.
Say you are learning a topic, it finally clicks for you, you feel like you could do anything, it’s a huge dopamine hit, to say the least. Then you move on to learning ActiveRecord for the first time just to realize you’re lost again(looking at you, week 2 of boot camp). It is humbling to see programmers get back up on their feet after not being able to solve a bug for hours, looks like we’ve got a knack for taking mental beatdowns.
Use the programming community as a resource, and don’t be stubborn about doing so. There will always be programmers out there to help you, that's why package managers and frameworks exist. READMEs are meant to be and expected to be, your guide into the unknown.
