Skip to main content

The GDS Way and its content is intended for internal use by the GDS community.

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
This page was last reviewed on 3 May 2024. It needs to be reviewed again on 3 November 2024 by the page owner #gds-way .
This page was set to be reviewed before 3 November 2024 by the page owner #gds-way. This might mean the content is out of date.