There should be a README for every NHSBSA Git repository. A user expects a README to help them:

• understand what the project is
• evaluate whether the project is useful for them
• learn how to use the project
• understand how to contribute to the project

You should write READMEs in plain english and define any technical terms that may be unfamiliar to someone new to the project.

Avoid using terms like ‘just’ or ‘simply’ when writing your README. You should not assume your user has any prior knowledge of the project.

Length of your README

A README should be an overview and list of instructions to help someone get started with your project.

If you find yourself writing a lot of content for your README, consider moving some of the more detailed documentation, such as API reference information or configuration advice, into a separate document. Please these in a docs folder within the same repository and link to them from the README.

Structuring your README

Use the NHSBSA template for READMEs.

• About the project
• Quick start
  • Building the application
  • Running the application
• How to contribute
• License

Test your documentation

Test your README instructions before you publish to make sure users can follow them. Ask a member of the team to try the instructions and make sure they work

---

Improve the playbook

If you spot anything factually incorrect with this page or have ideas for improvement, please share your suggestions.

Before you start, you will need a GitHub account. Github is an open forum where we collect feedback.