You show your GitHub project to people but they don’t understand what the code is about. Why should you take time to write a good README if they can simply “read the code”?
They won’t even look at your code if you don’t explain what’s in it for them. Why should anyone care about it?
What about making them curious about your project? It saves them time, it shows you care about good communication and that by writing good docs you probably write good code as well.
In the end, we write code for humans đ.
By the end of this post, you’ll know how to:
- Write simple yet useful READMEs for your GitHub projects.
- How to improve your chances of making a good impression next time you send a potential employer a link to your GitHub portfolio.
It may seem too much to learn and you’ll probably feel overwhelmed. Use this as a reference and do the homework. That’s a good starting point.
Let’s get started!
Improve your GitHub profile
Start by doing an ‘audit’ on your profile:
-
It’s a good idea to have a repository for each project. Your GitHub profile becomes a portfolio by itself. Add a personal README and up to 4 projects that you want people to see first. See my GitHub README as an example.
-
Write about you in your user section. Tip: instead of adding “I’m a early career developer looking for opportunities”, use powerful words that describe your skills. For example: “I help charities make data-driven decisions with Ruby”.
Position yourself as someone who provides value and not someone learning how to code. You’ll always be learning. Drive the focus to the value you generate instead.
How to write a good README
Let’s say you need to run this project on another computer. Would you know all the steps needed to install it again? Which files to look at first? Probably not.
Asking yourself questions like this one help you connect more with your users. Put yourself in their shoe’s and avoid jumping to conclusions.
Do they know which commands to run on the terminal? How to navigate through the project’s folders? What do they need to know about your project?
Even if they have experience with the programming language, they may have forgetten how to run commands. Readers from all levels will be able to appreciate your work. Including your future self.
The ‘How to Get Started’ section
The How to Get Started section tells the user which commands they will run and anticipate any dependencies they need to install first.
Here’s an example of a How to Get Started section for a Rails app:
This project depends on libexif. If you're on a mac, run `brew install libexif` to install it.
Run `git clone my_github_project` to clone the project.
Run `cd my_github_project && bin/setup` to install dependencies.
Then, run `rake install` to install this gem onto your local machine.
Run `app export` to generate a CSV file with the Exif data.
Run `cat output/*.*`. If you see a list of files, this means your setup is correct.
If relevant, add code snippets or images. Check out Carbon for creating awesome code snippets. Show, don’t tell.
Bonus tip: uninstall the project and go through the process of installing it again. If you had problems with one command, add “If you run into this error, run this command”.
Homework: Write a Badass README
- Choose one of your projects.
- Use this README checklist as a template.
- Review your README using the questions proposed on Tips for writing a good README.
- Congratulate yourself for developing a new skill đ„ł.
Good companies value good communication. I’ll never forget when the CTO of my first internship said: “you write well, that’s a good indicator that you have the skills to write good code, too”. It opened my eyes to how much communication skills matter.
Write good docs, write good code, make your readers happy. See you next time đ.
Did you like this article? Then you're gonna love these other ones: