Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 10 Mar 2020

READMEs for GOV.UK applications

This is a guide to writing and maintaining README documents for GOV.UK’s public repositories.

Who are READMEs for (aka what’s the user need)?

  • New starters to GDS
  • People joining a new team
  • People interested in our work
  • Developers on other teams

Template for new READMEs

# App name

One paragraph description and purpose.

## Screenshots (if there's a client-facing aspect of it)

## Live examples (if available)

- [](

## Nomenclature

- **Word**: definition of word, and how it's used in the code

## Technical documentation

Write a single paragraph including a general technical overview of the app.

This is a Ruby on Rails application that maps RESTful URLs onto a persistence
layer. It's only presented as an internal API and doesn't face public users.

### Dependencies

- [alphagov/other-repo]() - provides some downstream service
- [redis]() - provides a backing service for work queues

### Running the application


Documentation for where the app will appear (default port, vhost, URL etc).

### Running the test suite


Include any other edge cases, e.g parallel test runner in Whitehall

### Any deviations from idiomatic Rails/Go etc. (optional)

### Example API output (optional)

`one-line-curl-command with JSON response after`

Keep this section limited to core endpoints - if the app is complex link out to `/docs`.

## Licence

[MIT License](LICENCE)

## Versioning policy (for Gems only)

Benefits of using this template

  • it is consistent
  • it is scannable
  • functionality is shown in screenshots and links to live services
  • it has quick start information for new developers or interested third parties

One-line summaries on GitHub repositories

Who are these for? These are for people who scan the list in alphagov and need a quick overview.

  • Include information about whether it’s on GOV.UK
  • Try to tone down technical language - ‘Filtered search of content’ is better than ‘Faceted search interface’
  • Use the GitHub link field to link to the developer docs page for the repository, or otherwise the live service (if public facing)

A good example:

GOV.UK filtered search of public content

Things we shouldn’t put in the README

  • Full documentation of the API - if the app is complex or has a complex API, use the docs directory liberally, and link out to it from the README
  • Contributors - we can use GitHub’s native graphing tools for this
  • Contribution guidelines - use GitHub’s guidelines for this
  • Full licence - again, follow GitHub convention