The DfE technical guidance and its content is intended for internal use by the DfE community.

Adding a new guidance

Access

You need write access to the repository or you can raise a pull request from a forked repository.

Note that review apps only worked for pull requests raised in the original repository.

Publishing changes

Make sure to make changes in a branch. Every change should be reviewed in a pull request, no matter how minor, and we’ve enabled branch protection to enforce this.

Once the pull request is merged, the deploy Github action workflow runs the build and pushes the static site to AKS.

Review apps

Every pull request builds a separate review app. It is a unique version of the documentation implementing the changes from the pull request and pushed to AKS with a unique URL so it can be shared and peer reviewed. The URL is posted in a comment on the pull request.

Any change to the branch is automatically pushed to the review app after a few minutes.

When the pull request is closed or merged, the review app is deleted.

Guidance content

In the DfE Digital technology guidance repository, in the source directory, create a subdirectory representing the name of the guidance.

Inside the new directory, create an index.html.md.erb file following this pattern:

---
title: The Title of Your Page
---

# <%= current_page.data.title %>

Introduction of a couple of paragraphs to explain why the thing you're
writing a standard about is important.

## User needs

Why do we do this thing? Who is it helping?

## Principles

What broad approaches do we follow when we do this thing?

## Tools

What specific bits of software (commercial or open source) do
we use to help us do this thing?

Then make a pull request and inform maintainers in the #architecture, #developers and #tech-community Slack channels.

Secondary pages related to a guidance may be created in the same directory as <title>.html.md.erb. To hide them from the sidebar navigation, add field hide_in_navigation: true to the page header.

Common data

To avoid repeating content and simplify maintaining, common data can be centralised in site.json. For example:

"digital_tools": "/infrastructure/support/#digital-tools-support"

Can be referred to as:

[Digital tools support](<%= data.site.digital_tools %>)

Which will be rendered as: Digital tools support

Child pages table of content

A table of content for pages in subdirectories may be rendered automatically using:

<%= partial('partials/children_toc') %>

Page table of content

A table of content for ## Markdown sections (or <h2> in html) on the same page may be rendered automatically using:

<%= partial('partials/page_toc') %>

Review

The guidance must be reviewed and updated before the expiration date.

Previewing locally

To preview the site locally, we need to use the terminal. Install Ruby with asdf or manually (see version in the .tools-version file) and install Bundler.

Once you have Ruby and Bundler set up, you can install this project’s dependencies by running the following in this directory:

bundle

Whilst writing documentation, run a middleman server to preview how the published version will look in the browser:

make server

If all goes well something like the following output will be displayed:

== The Middleman is loading
== LiveReload accepting connections from ws://192.168.0.8:35729
== View your site at "http://Laptop.local:4567", "http://192.168.0.8:4567"
== Inspect your site configuration at "http://Laptop.local:4567/__middleman", "http://192.168.0.8:4567/__middleman"

You should now be able to view a live preview at http://localhost:4567. After saving a change the preview in the browser will automatically refresh.

The preview is only available on our own computer. Others will not be able to access it if they are given the link.

Build

If you want to preview the site exactly how it is published, you can build the static HTML files locally. It also helps debugging issues by running in verbose mode. Type the following:

make build

This will create a build subfolder in the application folder which contains the HTML and asset files ready to be published.

Check links

To check all hypertext links inside the generated documentation are valid run:

make check-links

It will build the site and check all the links. It takes a few minutes.

Accessibility testing

Install AXE Chrome extension or Firefox extension and analyse the pages using the developer tools.

Issues with the tech-docs-gem and govuk-frontend should be reported on the respective repository.