Template for README.md

README.template.md

[Project/repo title]

Table of contents

1. Motivation
2. Additional documentation
3. How to set up the dev environment
4. Testing
5. How to run it locally
6. How to deploy/install it
7. Backlog
8. Troubleshooting & FAQ

Motivation / Project description

• Why was this repository/project/component created?
• What exact problem does it solve?
• Who are the stakeholders involved?

Features

Please enumerate and describe the main features offered by this service/component/script/whatever.

Additional documentation

E.g. architecture diagrams if needed.

How to set up the dev environment

• Please explain the common prerequisites to run either the tests or the component locally (e.g. having a specific Maven version installed for a Java project).
• It might be a good thing to follow this idea.

Testing

How is this component tested?

• Manual tests vs Automated tests
• Unit vs Integration vs End-to-end tests

How to run the tests locally

• Precise instructions, with the specific commands, to run whatever tests are possible to run, including all the prerequisites.

How to run it locally

• Precise instructions, with the specific commands, to run the component/service locally.
• If there are scripts, name them, explain how to run them, their goal, etc. If that explanation is inside the script itself, at least mention here that they exist.

How to deploy/install it

• What is it needed to deploy this component? How to install it?
• Including dependencies needed, etc.

Backlog

Where and how do people additional things to work on for this component? Just an issue in the GitHub repo? Is there a specific Trello/GitHub project somewhere?

Troubleshooting & FAQ

TBD