What is a README file?
The readme file is the first thing a user will see when viewing your repository. It gives the user an idea of what the project is about, what language was used, what the terms and conditions are, what your project can do, shows screenshots of your running application, etc.
Why is it important?
This user could be a recruiter, your future boss or client. Therefore, it is important to note that the README of your project should answer the what, why and how of the project.
Therefore, it is important to include the most important information, give a clear description of the project and the technology stack used, and provide links and further instructions that may not fit into the README file to avoid unnecessary searching through all the other files, which could cause the user to simply lose interest and move on to the next potential employee.
I cannot stress enough how important it is to write good documentation about the project. Not only is the user looking for information about the project itself, but they also see your documentation skills, your attention to detail, which could bring you that much closer to getting a job.
If you've read other articles of mine, you've probably noticed how important it was for my career to have learned other skills besides programming that ultimately helped me get a job. And good documentation was one of them.
What to put into a readme?
Here are some guiding questions that will help you:
- What is the project about?
- Why did you develop it, what was your motivation?
- What problem does it solve?
- What have you learned?
- What makes your project stand out?
I will show you how to convert these questions into text.
Possible structure
Description Purpose and description of the project so that the person reading your portfolio can understand the project in the first few seconds of reading the project information.
Tech stack Tech stack including the programming languages, libraries and frameworks your project uses (e.g.: Python, React, ...). If you have a front-end application that uses an external public API, please mention this.
Design Examples of user interfaces associated with the project. If the project has a user interface, you can insert a GIF, video or image of the user interface.
If it is an application that runs on the terminal, you can create a GIF that shows how to work with it. This is good for giving an idea of how to interact with the application and what someone would see when they run the project.
Features If your project has a lot of features, you should add a Features section and list them here.
How to run the project Instructions on how to set up, run and use the project. This is good if someone wants to start the project from scratch, they should find everything they need to know in the project's README without needing any help from you.
If it's simple, you can include it in the readme file. You can also refer to another file in your project if the instructions are longer.
You should also host your project e.g. using Netlify, so users can open the deployed app and use it right away to see how it works. (Keep in mind that not every recruiter looking at your GitHub profile has a solid understanding on how to set up a project locally.)
How to style a readme?
The .md extension in README.md stands for Markdown, a lightweight markup language with a simple syntax for text formatting. It is a very simple language for creating beautiful and presentable readme files for GitHub.
Therefore, you can use typical markdown language, like
# Heading 1
## Heading 2
### Heading 3
Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
1. First ordered list item
2. Another item
⋅⋅* Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
⋅⋅1. Ordered sub-list
4. And another item.
[I'm an inline-style link](https://www.google.com)
[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
and much more. Make sure to get the most out of it.
Here are two examples of my beginner projects I applied for jobs three years ago. I would now make them even more detailed as described above.
{% embed https://github.com/YurisCodingClub/sos-animals %}
{% embed https://github.com/YuriDevAT/nikki-my-diary %}