Writing READMEs
There should be a README for every GDS GitHub 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 your project.
If you want help writing a README, you can ask a technical writer in #tech-writers on Slack.
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.
Some project teams at GDS like to include these in a docs folder within the same repository and link to them from the README.
Structuring your README
Use the alphagov template for GDS READMEs.
Test your documentation
Test your README instructions before you publish to make sure users can follow your documentation. You can also ask a:
- member of your team to try the instructions and make sure they work
- technical writer to review the content