DEV Community

loading...

How to write a good ReadMe.

Mei
I'm a Full Stack Software Engineer who works in React and Java Spring.
・2 min read

What is a ReadMe?

“A README is like the face of your project. It is the first file a person should read whenencountering a source tree, and it should be written as a very brief and giving very basic introduction to the software” - A Beginners Guide to writing a Kickass README

A good quality README should:

  • help people engage in the project as well
  • get the attention of users better since it is a direct way to explain why this project matters, and why people should use and contribute to the project
  • help a new user get started, e.g. how to compile, how to install, and how to start integration

So, what makes a good Readme?

  • Project Title/Motivation – usually some sort of short concise description of the project. This can reference other documents (like requirements) if need be.
  • Getting Started - These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
    • Prerequisites (any additional libraries needed to be installed)
    • Step by step guide to getting the project started in a dev environment
  • Running Tests and/or Test Strategy - Explain how to run the automated tests in the project/system.
  • Deployment – Notes on how to deploy this on a live system
  • Versioning – Any comments on versioning system, link to tags etc.
  • Contributing – Details on code of conduct/team agreements.
  • Authors – list of all authors (sometimes indication of who started the project).
  • Licensing – details of licencing agreement (possible link to licensing file).
  • Acknowledgements – details of any acknowledgements, inspiration, etc.

To start with your Readme file, why not take a look at this website? 😊 https://readme.so/editor

Discussion (0)