How do you like your cup of GitHub?
If only your repo had a README.md
Introduction
About 5 years ago (in 2017) I entered grad school for Computer Science with very little programming/coding experience. A professor whose class I was listening in on said someone from a non-technical background or with little programming experience could definitely succeed in this major. He said this after I asked him during a class break and informed him that, I graduated as an Engineering major and technically came from a tech background, but more electrical as opposed to programming and was very interested in the Computer Science program at this school.
Years ago, when Computer Science topics were discussed, the majority of the discussion was about how intensive and challenging the programming courses were. It always seemed to me that in order to even consider taking a Computer Science course, one would need to have been born with some level of genius.
I associated that tone (even today) with imposter syndrome, which is the feeling (from my experience as a Computer Science student and now as a developer) that one lacks the necessary skills to accomplish a task based on one's current knowledge or expertise in a particular area and that others are better equipped or better skilled in the area. For some reason, however, I never lost my curiosity about the major; there was a part of me that wanted to explore what Computer Science was about, and I didn't realize it until I took the class (in 2013) that opened my mind to the world of software development...I was hooked.
It took one C programming class
If imposter syndrome had a mascot I probably would have been it my entire first year of grad school. My only drive to pursue a Computer Science degree was sparked by one C programming class I had to take during my undergraduate studies, which lasted at most 4-6 weeks. Most of the class was theoretical with a few coding sessions that taught the basics of C syntax.
#include <stdio.h>
/*My first program in C*/
int main()
{
printf ("Hello World");
return 0;
}
I was excited at the idea of being able to design, create, and build something, a piece of software simply by using code. I mean, I enjoyed my time studying Electronic (Information) Engineering, but I simply could not brush off the bug that was the C programming class. Soon after the class ended, I remember signing up for freeCodeCamp a few weeks later, to learn more about programming and coding in general.
My undergraduate studies were being taught in Mandarin and that was a challenge on its own, trying to keep up with coursework and making sure I understood the content enough to clear the exams. So even though I had a strong desire to teach myself how to code outside of class, the time was never really enough, but throughout the remaining three years or so years of my undergrad, I’d find myself learning some fundamental concepts of HTML, CSS, or other languages like Python.
Grad school as some people may already know is building on top of knowledge already acquired from lower degree levels. Since I had no background in Computer Science, the professor said “..it is possible, but you would have to work hard”. I took his words literally, I spent several hours in the library and designated study halls trying to study in English (yes I had to reprogram my mind to be taught and study in English again), which at times felt a little strange. I tried to find different approaches to learning programming languages relevant to the courses I was taking each semester, but I’d only get as far as learning the basics, but never really grasping the logic of the language itself.
Most of the courses came with some aspect of coding, however, it was always in a group setting, so there was always one person who could code well, another who was good at project management for example, and another who was a good communicator. It was during these group projects that I felt like I was imposing on the course that was Computer Science, I felt like I did not quite belong because I could not understand the logic of programming as well as a classmate who had their bachelor’s in Computer Science (or sometimes was a bachelors student as some courses were mixed).
I chose to consciously fight imposter syndrome by studying smarter and my confidence as a Computer Science major started to grow, however, I knew that if I wanted to successfully acquire a job in the industry I had to learn and master at least one programming language and this is where reality started to sink in. As I was nearing the end of grad school I had to seriously consider what career path I wanted to take, and for the most part, if I wanted to remain within the general field of technical Computer Science…I needed to know how to code and think as a programmer, but where and how do I start?
GitHub with a README.md, please
I learned early on during a class project that GitHub is a tool widely used for programming projects and comes in handy when a group of people are working on the same coding project at around the same time. I had probably created an account right around my first year (2016), but never really practised coding enough to have anything to show on there (no contributions until 2020). Strangely enough, I started using GitHub a few months after I graduated.
After handing in my Master's thesis on June 2019, I graduated with good grades and was grateful for the journey and experiences in those 2 years, but at the same time, while holding my diploma and preparing for life after graduate school, felt like an owl in the middle of a snow-covered forest in winter with so many different directions to fly but had to decide on a path that would lead to a career I would enjoy, thrive in and hopefully make a meaningful contribution to. So I decided to take time to seriously teach myself how to code while at the same time interviewing for full-time roles.
In doing so I paid a lot of attention not only to the languages that were relevant to the industries I was interested in entering, but I started to pay more attention to how my GitHub profile looked because some companies would ask if I was a candidate had one, and even if the type or number of projects I had on my profile did not play a role in being invited to an interview, I curated a list of projects that were written in a language I learned was increasingly popular or widely used (and I was interested in) but also purposely structured my repositories in a way that I as a first-year grad student would have enjoyed and perhaps got inspired to read code more effectively.
Bugs are inevitable when coding, at least in my experience, and my primary source of hunting for solutions (aka debugging) when the error message is not clear is StackOverflow via Google and GitHub. Most of the repositories I would come across when searching for solutions to bugs in my code had little information regarding the actual code in the README.md and most times it didn’t have the file altogether. The README.md is usually the introduction to the repository, it tells the reader what is contained in the code and how to use/access that code which also motivates the reader to stay and read the code for a solution or hint to one.
What to include
Code repositories should include a README.md containing at least the most basic information about your code project. In most cases, a short description of the app, its name, and the technologies used are included at a minimum. My README.md usually contains as much information about the web app as possible, especially if it is being submitted for review for a coding/programming challenge or hackathon. I know it will be viewed by other developers and probably by non-coders as well, so I try to provide as much information as possible in order to make the code easier to comprehend and use. In this regard, this is what I’d typically include:
App title or name
App description
A table of contents
Screenshots: (~3) to highlight important features of the app
Technology stack: what tools/languages were used to build the software
Features: what can the end user expect i.e what does the app do
How to use the app: how can other developers use the app i.e what software is required to run the app
Author: who are the contributors i.e who developed the app
Miscellaneous: it is encouraged to add a license file in the root of your repository, in most cases I add a license badge which is displayed at the bottom of the README.md file
The image above is a README.md in my Storefront app repository.
I decided that since I found a README.md to be helpful when looking to fix bugs effectively and since the majority of repositories I encountered did not have one, I thought that perhaps curating my repositories so that each contained a README.md even if it was short, but had the necessary information, that it might help another coder who was as passionate about their code as they were about the presentation of their code as well as its repository. With all that said it’s safe to say that not every coder/programmer has the time or desire to have a well-structured or somewhat decent README.md as at the end of the day what matters is a working coding solution and/or hint to bug fix.
In Conclusion
I still consider myself a student of life and science, so even though I have graduated and still in pursuit of that which is my significant contribution to the field of science, perhaps the current state of my GitHub profile is but a small coded storybook to myself as a first-year grad student who wasn’t sure she would fit into the field that is Computer Science enough to share and create solutions that would make planet Earth (and the extended milky way) a better place to inhabit. With each repo representing a book chapter showcasing some level of progress and a reminder that yes it is indeed possible. Whichever way you like your GitHub (README.md) just make sure you try and keep at it.
Thanks for reading…happy coding!