Recipe for a good readme

#codenewbie #beginners #writing #webdev

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.

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 readmes 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:

_{Sylwia Vargas}
💻 📖 🐛 💡

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