Good project readme is a good practice in code documentation and also helps you stand out when looking for a job. Here are some tips & tricks for writing one.
Table of contents:
- Write it well
- Include title, description and table of contents
- Explain setup and stack
- Know your audience
- Mention the license
- Shout out contributors
- Invite contributions
- Explain next steps
1. Write it well
Good documentation isn't boring or unapproachable. Quite to the contrary — good docs will make it easy for the user to follow what's being written. You don't need tech vocab — in fact, you are better without it. Plain English will suffice. In fact, the reason why people love React docs is because they are so well-written: split in digestible chunks, written in plain English, with good links.
You can also allow yourself to find elaborate analogies. A student of mine was really excited to find this bit in otherwise pretty boring and technical Ruby docs.
2. Title, description and table of contents
They should be concise and reflect what the project is about. Here is a readme I wrote for Covid-19 risk calculator, one of the projects I worked on. You know from the get-go what to expect from the project. Moreover, the attached table of contents makes it easy for the user to navigate to the appropriate section.
3. Setup and stack
Don't assume that everyone is familiar with your app's stack, or that they remember how to get started in it. Describe how to clone the repo, how to install the dependencies and how to run the project locally. Include links to the docs of the technologies used so the user can be more independent in navigating your code.
4. Know your audience
Who are you writing the readme for? Is it for another dev who will take the project over? Is it for another dev who will take the project over? For recruiters? Or just for good documentation for later? Here are some examples of the readme
s I've written with different demographics in mind:
5. License
Even though you always have full rights to your project, it's good to be explicit about it. This page is helpful in choosing an appropriate license.
6. Contributions
If your project is Open Source and you envision a future in which people would like to contribute to your project, specify how to do it. This is how I usually phrase it:
Pull requests are welcome. Please make sure that your PR is well-scoped.
For major changes, please open an issue first to discuss what you would like to change.
7. Contributors
This is handy when you collaborate with folks. I recently noticed that Kent C. Dodds has a very beautiful way of dealing with presenting contributors in his projects and I took inspiration from him. This code snippet:
<table>
<tr>
<td align="center">
<a href="https://github.com/sylwiavargas">
<img src="https://avatars2.githubusercontent.com/u/45401242?s=460&u=2efe4366e8a6c7e8732daaaf8373250e7c8cfdd9&v=4" width="200px;" alt=""/><br/><sub><b>Sylwia Vargas</b></sub>
</a><br />
<a href="https://github.com/sruti/covid19-riskfactors-app/commits?author=sylwiavargas" title="Code">💻</a>
<a href="https://github.com/sruti/covid19-riskfactors-app/commits/master/README.md" title="Documentation">📖</a>
<a href="https://github.com/sruti/covid19-riskfactors-app/issues/created_by/sylwiavargas" title="Bug reports">🐛</a>
<a href="#ideas-sylwia" title="Ideas, Planning, & Feedback">💡</a>
</td>
</tr>
</table>
Results in this table:
8. Next steps
Or "known issues". Describe what you wish to implement or fix next if time allows. This is an opportunity for you to show that you are a self-aware dev who knows that no project is ever finished or perfect.
Photo by Lucas Ettore Chiereguini from Pexels
Top comments (4)
I know documentation is super important and can set the tone for your application. Thanks for a handy foundation!
Thanks for that! I recon we should be more mindful to our dear doc readers, they're so few of them.
Kent is using a table to design the cards? The good old days :)
Yes, readme readers are an endangered species :D
What do/would you use for the cards in a readme?
Btw. I have just checked your docs — I always appreciate well-written readmes!
I would start with 9elements.com/bem-cheat-sheet/#card+i