Skip to main content

Data Services technical documentation

This site is a central store of technical documentation for the data community working on GOV.UK, and should be the default place to record information and decisions. Any private or sensitive information should be linked to from here rather than written here directly.

Use this documentation if you need to find out information on:

Contact one of the Data Services teams if you have any questions or feedback.

Contribute to the documentation

This project uses the Tech Docs Template, which is a Middleman template that you can use to build technical documentation using a GOV.UK style.

It is easiest to contribute by editing files directly in GitHub, but you won’t be able to preview your changes. To preview your changes, you will have to install some software.

Make changes

To make changes to the content of this website, edit files in the source folder of this repository.

You can add content by editing the .html.md.erb files. These files support content in:

  • Markdown
  • HTML
  • Ruby

👉 You can use Markdown and HTML to generate different content types example-content and Ruby partials to manage content.

Contribute without previewing your changes

  1. Edit the files directly in GitHub
  2. Open a pull request
  3. Request review and get approval from another contributor
  4. Merge the pull request

When the pull request is merged, GitHub will automatically render the changes that you made. It will take about a minute. You can monitor the progress by viewing the GitHub action in your browser.

Preview your changes

Follow the steps in the section install the tech docs template. Then follow the steps below.

  1. Use git to clone this repository to your device.
  2. Navigate to the cloned repository on your device.
  3. Activate Ruby version 2.7.6 in your current terminal by running rbenv shell 2.7.6.
  4. Use rbenv to install all the required Ruby gems by running rbenv exec bundle install.
  5. Make some changes to the content of the site, in the source directory.
  6. Preview the changes by running bundle exec middleman serve.

👉 See the generated website on http://localhost:4567 in your browser. Any content changes you make to your website will be updated in real time.

To shut down the Middleman instance running on your machine, use ctrl+C.

If you make changes to the config/tech-docs.yml configuration file, you need to restart Middleman to see the changes.

Create a new website

Follow the steps in the section install the tech docs template. Then follow the steps below.

  1. Activate Ruby version 2.7.6 in your current terminal rbenv shell 2.7.6
  2. Install an old version of a dependency rbenv exec gem install contracts -v 0.16.1
  3. Install middleman rbenv exec gem install middleman
  4. Use middleman to create a new website rbenv exec middleman init <folder-name> -T alphagov/tech-docs-template where <folder-name> is the name of a folder to create that will contain the website
  5. Navigate into the folder that was just created cd <folder-name>
  6. Install packages that the website requires rbenv exec bundle install

Install the tech docs template

You will need to install the following software.

  • Xcode command line tools (if you are using a Mac)
  • Node.js
  • Ruby
  1. Install Xcode (if necessary) and Node.js by following the instructions in the tech docs template documentation.
  2. Install rbenv. The Tech docs template docs recommends installing RVM instead of rbenv, however the GDS Way recommends rbenv.
  3. Open a terminal.
  4. Use rbenv to install Ruby version 2.7.6 by running rbenv install 2.7.6. The Tech docs template docs recommends the latest 2.7.x version listed at https://www.ruby-lang.org/en/downloads/ which is a later version, 2.7.8, but rbenv will only install 2.7.6, and neither version is maintained anyway.

Next follow the steps in the section Create a new website or Preview your changes.

Troubleshooting

Do not run bundle update because the website only builds with the current package versions, given the old version of ruby. You could try using a more recent version of ruby, and recent versions of all the packages.

Run bundle exec middleman build --verbose to get detailed error messages to help with finding the problem.

Licence

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

This page was last reviewed on 28 November 2024. It needs to be reviewed again on 28 May 2025 .
This page was set to be reviewed before 28 May 2025. This might mean the content is out of date.