Write clear READMEs to increase your chances to find your first coding job
Why a developer should always invest her time to write a clear README for their public repositories
Why a developer should invest her time to write a clear README for their public repositories
In this article, I would like to share with you my little observations on how many junior developers failed to convince me to hire them by not putting a README to their repositories.
Useful links on how to craft a stunning README at the end of the article.
What is README?
Usually, README is a file in the repository of software/project that briefly explains it.
README file is there to pitch your work.
README is not your documentation (unless it can be fitted into one page).
Why should you make it?
If you make your repository public, you most likely will be judged by it. Especially, when you apply for a new job with your GitHub/GitLab account in your resume.
I have been involved in hiring interns/junior software engineering positions a few times throughout my career. On average, I saw only 1 out of 7 candidates to mention their profiles on GitHub/GitLab. Very few of those candidates would have a README attached to their repositories.
I assume that those candidates attaching their GitHub profiles think that recruiters/recruiting engineers will dig into the code to figure out what is going on over there. That does not happen. The main reasons for that are:
They do not have time for that
They are not technical
Even if they are technical, they might not know the language/structure of the code that you have written
As a result, you might have strong coding skills and a decent project in your portfolio, but no one will know that without a README that would explain what happens.
Drawbacks of not having a README at all
When people apply for internship/junior positions most often they have little to nothing to show to prove that they are good candidates. They got their educational background. Usually, that is it. So, your Github account is the most valuable thing in your resume.
As a technical person, when I see no-README repositories of people applying for a job I question their soft skills’ level. At least, I will think that you are OK to leave your work undocumented. Obviously, it does not help you to pass to the next processing level.
Drawbacks of having a poor README
You tried to explain what it is all about in your README, but it is hard to understand (to me). I would count you a point if you apply for a junior-level position, but it would be a problem if you want to be a senior.
Soft skills are critical for senior-level engineers. Communicate the task, and explain your work might be even more important than your coding skills.
Senior-level engineers have to be able to clearly explain what they have built.
Advantages of having a clear README (for your resume)
You look professional
Anyone in the hiring loop can evaluate your efforts
You are able to clearly explain what you built
How to make a good README?
0. Make a short self-explanatory repository name
Yes, I want to be able to guess what is inside just by a name.
Usually, it is not possible to explain all you did in just your repository name. Instead, you should pick only one feature, and try to use it as a repository name.
1. Concise one-liner
One-liners are hard. It has to attract the reader’s attention.
Try to impress your reader with 60 characters.
Your task here is to make me think something like:
“Interesting, how did she do that? I want to investigate her repository further”
2. Demo it
Show me what it does. A screenshot or a GIF would be nice to have.
3. Explain which purpose it serves
Oh yes. We do not code just to code. We code to resolve the problems. We code to bring value to our companies. So, even if you did it just because you liked it. I want you to explain the value it brings to a specific type of person/company.
4. Promote it
Now, when you have a clear README, try to get someone’s attention. Get some feedback. Get some stars.
Try to share it on HackerNews or some subreddits.
Other things that are good to have in your README:
How to install
Quick Start
Mention libraries which you used to produce your work
Conclusion
Searching for your first coding job with repositories that have a well-crafted README will increase your chances to receive a call back from recruiters.
Still, this article is about gaining extra points to your resume, having a good README only will not make you a good candidate.
How to make a README that others want to read
About meMy name is Artem, I build newscatcherapi.com - ultra-fast API to find news articles by any topic, country, language, website, or keyword.I write about Python, cloud architecture, elasticsearch, data engineering, and entrepreneurship.