Helder Berto
Published on

Structuring a better README for your projects

In this article, I will share some of the thoughts I keep in mind to create a better README for my projects.

Simple structure for a README file

  • Functionality gist + a demo if applicable into a REPL like (Codesandbox).
  • How to install.
  • Setup.
  • Examples/usage.
  • How to contribute.
  • Clearly defined public API.
  • Turn your project more discoverable (Github, NPM).

Make your user experience easier to contribute

  • Concise issue templates with clear points that will help to debug and understand issues.
  • Clear pull-requests templates to users identify if everything is well to open the MR.
  • Leverage your Github templates overall it will turn your life and the contributors easier.

Improve the project quality

  • Github actions for linting, tests & conventions checks.
  • Use commit linters to keep the consistency of the commit messages.