alphagov/govuk-frontend-docs

Technical documentation for GOV.UK Frontend

GOV.UK Frontend 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.

You’re welcome to use the template even if your service isn’t considered part of GOV.UK, but your site or service must not:

• identify itself as being part of GOV.UK
• use the crown or GOV.UK logotype in the header
• use the GDS Transport typeface
• suggest that it’s an official UK government website if it’s not

👉 To find out more about setting up and managing content for a website using this template, see the Tech Docs Template documentation.

Before you start

To run this project you need:

• Ruby
• Middleman
• Node.js

Making changes

To make changes to the documentation for the Tech Docs Template 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

👉 Learn more about configuring your website.

Installing dependencies

• run bundle install for Ruby dependencies
• run npm install for JavaScript dependencies

Preview your changes locally

To preview your new website locally, navigate to your project folder and run:

bundle exec middleman server

👉 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.

Build

To build the HTML pages from content in your source folder, run:

bundle exec middleman build

Every time you run this command, the build folder gets generated from scratch. This means any changes to the build folder that are not part of the build command will get overwritten.

Troubleshooting

Run bundle update to make sure you're using the most recent Ruby gem versions.

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

OpenSSL issues on newer versions of MacOS

Because of some quirks with OpenSSL on newer versions of MacOS, you might run into an error with eventmachine while running bundle install.

To fix this, run:

brew install openssl
bundle config build.eventmachine --with-cppflags=-I$(brew --prefix openssl)/include
bundle install

Testing

To run the linter and Ruby tests, run bundle exec rake.

To check for broken links in the guidance, run npm run check-links.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

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

govuk-frontend-docs's Issues

Rename govuk-frontend-docs default branch to `main`

What

Rename the master branch to main.

Why

Many communities on GitHub are considering renaming the default branch name of their repository from master, as this terminology can be offensive. Statements and guidance have been published by Git here and GitHub here.

New GitHub repositories use main as the name for the default branch, so it makes sense that we should follow this convention, as well as matching what other teams within GDS are doing so we are consistent.

Additional Info

GitHub have made it easier for teams to rename branches. When we rename the branch, we get the following for "free" without having to do anything ourselves:

• Open PRs and branch protection rules changed automatically
• Web requests for the old branch name are redirected to the new branch name
• API requests for the old branch name return a Moved Permanently response
• A notice is shown on the repository homepage to notify contributors, maintainers and admins to update their local copies of the repo
• A notice is shown to contributors who git push to the old branch

Who needs to know about this

Developers

Steps to follow

• Raise PR to switch functionality that relies on master and to update any documentation
• Once the PR has been approved (not merged!), rename the master branch to main in the Github UI
• Double check branch protection rules
• Double check webhooks
• Double check any deploy systems, e.g: Heroku, that may have it's own config
• If the repo uses Travis: Travis has its own idea of what the 'default branch' is which is synced once a day. You can manually trigger a sync by going to https://travis-ci.com/account/repositories and pressing 'sync account'.
• Merge the PR
• Check everything is still working as expected, e.g: build and deploy. If so, double check there is a main branch present and no old master branch present.

Done when

• The default branch is named main
• Update Travis config to deploy only when on the main branch
• Update indexing check to look for main branch
• Documentation has been updated to refer to main rather than master
• Check local setups still work
• Update the pinned issue on this repo saying the work has been completed
• Update the progress list in the govuk-design-system pinned issue

Update documentation to reference new ways of importing components

What

• Update the guidance on importing CSS, assets and JavaScript to reflect the changes in alphagov/govuk-frontend#1797.

• Check if there are other parts of the documentation that also need to be updated.

Further detail

With the changes in alphagov/govuk-frontend#1797, the preferred way to import a subset of the components will be to do something like:

@import "govuk/base";

@import "govuk/components/button/index"; 
@import "govuk/components/details/index"; 

If using a Sass compiler that supports index files, this could just be:

@import "govuk/base";

@import "govuk/components/button"; 
@import "govuk/components/details"; 

You can still import a single component without having to separately import its dependencies:

@import "govuk/components/button/button";

However, this is only really meant to be used when you need to import a single component in isolation, e.g. if you're creating a React component.

Why

Importing the components using the index file avoids re-importing the 'base' (settings, tools and helpers layers) multiple times, improving compilation times.

Who needs to know about this

@m-green, @36degrees, @hannalaakso

Remove redundant colons from code example titles in Sass API Reference

What

Remove redundant colons from code example titles in our Sass API Reference.

Why

It's inconsistent with our practice elsewhere in the Sass content. Usually, for a code example title, we just display a word, without punctuation. However, there are some instances where a colon displays after the word. For example, there's a colon after the word 'Example' here, but none after the word 'Usage':

Who needs to know about this

Laurence, Eoin

Done when

• Developer puts colons inside an 'if block,' so that colons only display as part of a description, as here:
  

Fix accessibility issues by updating the govuk_tech_docs gem to 2.2.2 [before 31 March]

What

Update the govuk_tech_docs gem from 2.2.1 to 2.2.2.

Then check if the update has fixed the hidden-content issue described in the guidance for accessibility-fixes.

Why

Version 2.2.2 of the Tech Docs Template fixes some outstanding issues with version 2.2.1. For example, users being able, when they use the search field, to focus elements that are 'hidden' behind other content.

Done when

• Gem updated
• Verified that users cannot focus hidden elements by using the search field

Move CI/CD to GitHub Actions

What

Move Frontend Docs' CI/CD from Travis to GitHub Actions.

Why

Travis' changes to our plan means that builds are getting stuck in a queue, which means they can take around 30 minutes to run.

Given that the direction of travel for the organisation seems to be towards GitHub Actions, and to be consistent with the approach we're taking with the Prototype Kit, move to GitHub Actions.

Who needs to know about this

Hanna, Laurence, Eoin

Further detail

Travis currently (as per the config) does two things:

• Builds the site and runs a link checker
• On the master branch, if the site builds and link checker passes, deploys the site to PaaS

Equivalent jobs need to be run using GitHub Actions.

There's an example of a workflow that deploys to PaaS from National Lottery Heritage Fund here:
https://github.com/heritagefund/funding-frontend/blob/master/.github/workflows/deploy-to-production-workflow.yml

We need to make sure that the production site can still be indexed, as the check is currently based on the TRAVIS_BRANCH environment variable.

We should make sure that the secrets are stored at the environment level with branch protection, as per https://github.com/alphagov/design-system-team-internal/issues/446.

Done when

• Use of secrets signed off with IA
• Existing open PRs merged / closed where possible to avoid needing to rebase
• GitHub Actions config added
• GitHub secrets added at environment level with branch protection
• Travis config removed
• noindex meta tag condition updated
• Required status checks updated
• Updated CODEOWNERS file
• Documentation updated:

govuk-frontend-docs/.rubocop.yml

Line 5 in 655c6e2

# Exclude `/vendor` because on Travis other gems get installed there

govuk-frontend-docs/config/tech-docs.yml

Lines 35 to 36 in d62c8d3

	# Set dynamically in config.rb depending on TRAVIS_BRANCH
	# prevent_indexing: false

Better group items in the Sass API reference

What

Group helpers and objects into themed sub-groups.

Why

This will help users navigate within the Sass API reference.

For example, colour-related helpers are currently separated out from the other helpers, but there are other sensible themes that most of the helpers could sit within.

Add Github issue templates to govuk-frontend docs

What

Introduce Github issue templates to the frontend docs repo. We should introduce the following templates to match govuk-frontend:

• Bug report
• Feature request
• Internal template
• Link to reporting a security vulnerability
• Link to get in touch page

The frontend docs may also benefit from a separate template for documentation. Whoever picks up this card, it might be worth looking at the draft documentation template and seeing whether it will fit/work alongside the other templates.

Why

In https://github.com/alphagov/design-system-team-internal/issues/349 we published a set of Github issue templates on one repo (govuk-frontend) for a trial period. We have analysed the data and the templates seem to be well used and, when used, most sections are filled out where applicable. The automatic labelling has helped improve the triage process and categorise issues. The support data has changed a little since November, but it's difficult to pin down why - it doesn't look like a direct impact of the templates.

Tell users that they can include a nonce on the inline script to allow it as part of their Content Security Policy

What

Document the alternative approach of including a nonce on the js-enabled inline script in the template in order to allow the script to execute under a content security policy, as introduced in alphagov/govuk-frontend#2246.

Tell users how to add the nonce in both HTML and when using Nunjucks.

As per best practise, make it clear that nonces should:

• be unique for each HTTP response
• be generated using a cryptographically secure random generator

We might also want to say that they:

• should have sufficient length, aim for at least 128 bits of entropy (32 hex characters, or about 24 base64 characters).
• should be avoided for script tags that have any untrusted / unescaped variables within them

Alternatively, we could link to external guidance on best practises for using nonces with CSP.

Why

It may not be practical for all users to include the SHA hash in their content security policy as we currently recommend. We're making it possible to pass a nonce attribute to be set on the script instead. It is critical to provide a nonce that cannot be guessed as bypassing a resource's policy is otherwise trivial.

We should document the alternative approach so that users are aware of the options, although recommend the hash solution as nonces may in some cases be easier to bypass.

Who needs to know about this

Tech writer, developers

Further detail

• Content Security Policy Quick Reference Guide on nonces
• MDN docs

Done when

• The documentation on CSPs includes setting a nonce as one of the possible solutions.

Configure repo settings and permissions

What

Ensure that this repo is set up correctly, so that:

• the right teams and users have access
• features that are not used are disabled
• it behaves consistently with our other repos
• it has a suitable description and URL (once the documentation site is live)

Why

• As maintainers, we need to have access to make changes to the documentation
• As maintainers, we need the repository to behave consistently with our other repositories

Done when…

• Access permissions are sensibly configured
• Repo settings reviewed for suitability and consistency

Add explanatory text and improve headings in Sass API Reference

What

Add explanatory/introductory text under headings in Sass API Reference. Possibly also revise some headings to make them more meaningful to users.

Why

Because of how the Sass API Reference is generated, no explanatory text displays under its headings. This means we are not telling users what the different sections can help them do.

There may also be an impact on accessibility - using headings that do not appropriately describe their related content is a failure of WCAG 2.4.6: Headings and Labels.

For example, would anyone coming to this content for the first time necessarily know what we mean by 'Assets'/ 'Settings' here? 👇🏻 Or even what the 'Sass API reference section' is for, generally?

Who needs to know about this

Laurence, Eoin

Done when

• we understand how 'group descriptions' work in SassDoc
• create content to add to headings (or 'groups', as they seem to be called) in govuk-frontend*

*However, the bulk of this work will be in the govuk-frontend-docs repo.

Configure Zero downtime push to use health checks

What

Configure Zero downtime push to ensure health checks pass as part of the deployment.

Why

To ensure that a deployed site has built correctly (if the health check doesn't pass the deployment is rolled back).

Who needs to know about this

Devs

Done when

• When the build log shows that the health check has run and passed

Use mixin ‘descriptive title’ rather than code as primary heading in Sass API reference

What

Decide whether to use the mixin 'descriptive title' (for example, "Common link mixin"), instead of the mixin code (for example, govuk-link-common), for primary headings in the Links section of our Sass API reference.

Why

This is an example of how mixin content currently displays, with the code first and the descriptive title second:

Would it be more meaningful to users if we displayed ‘Common link mixin’ first (and so on for the other mixins)? Are they likelier to think “I’m looking for govuk-link-common” or “I’m looking for a common link mixin”?

Who needs to know about this

Designers, Developers, Technical Writer, User Researcher

Done when we

• carry out any user research required
• decide whether to use the descriptive title as the primary heading
• implement agreed changes, if any

Improve Links section of SASS API reference

Related documentation

SASS API reference | Links

Suggestion

• Provide explanatory text about how this section helps users
• Display subsections in a more logical order
• Make presentation of content more consistent
• Improve navigability (for example, by inserting a table of contents)

Evidence

#23 lists SASS API reference as a content area we should improve. So does this doc on improving Design System/Frontend content.

Also, now that we're adding new mixins (see alphagov/govuk-frontend#2183), it seems like a good time to make the Links section more user-friendly.

Update the Frontend Docs to use GOV.UK Frontend v3.8.0

What

Once GOV.UK Frontend 3.8.0 has been released, update the Frontend docs to use it.

Why

So that the documentation reflects the latest release of GOV.UK Frontend.

Document how to configure Content Security Policy (CSP) to work with the inline 'js-enabled' script

What

GOV.UK Frontend page template contains an inline script tag which adds the js-enabled class. Content Security Policy (CSP) can block inline scripts.

We need to tell users how to allow the script in their CSP by including the hash of the inline script tag: sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU=. This is discussed in alphagov/govuk-frontend#1811 (comment).

An example CSP could look like

Content-Security-Policy: default-src 'self'; script-src 'sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU='

This documentation should probably be added as a new section under JavaScript.

We should mention that:

• we recommend teams talk to their security specialist when creating their CSP.
• we will treat any changes to the hash as a breaking change but we don’t expect the script tag to change much, if ever, so the hash should stay fairly static over time.

We could consider mentioning that teams don't need to make any changes to the script tag itself. A user who recently reviewed our workings doc on this assumed that they would also need to add an attribute to the script tag because the various ways to solve this problem (hash, nonces, SRI) all do things slightly differently and can be confused with each other; the user recommended that we confirm in our docs that no markup changes are needed.

Why

Teams have reported this as an issue and we have no guidance to help them resolve it:
alphagov/govuk-frontend#1811
alphagov/govuk-frontend#1657

Who needs to know about this

Mark, developer

Further detail

We have an inline script tag in the page template to prevent a flash of content for example on accordion and details components.

Currently, if you include the page template in your application and your application implements a CSP, the inline script could be blocked from running and you might see a warning about this in the console, eg.:

Refused to execute inline script because it violates the following Content Security Policy directive: "default-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU='), or a nonce ('nonce-...') is required to enable inline execution. Note also that 'script-src' was not explicitly set, so 'default-src' is used as a fallback.

Done when

• We've published the documentation in Frontend dev docs
• Optional: We could announce the new docs in our channels since they won't be flagged in Frontend release note

Set up continuous deployment of the master branch

What

When the master branch changes, deploy the built site to the PaaS.

Why

As maintainers, we want the live site to reflect changes as they are approved and merged, without having to manually deploy the site.

Further detail

This will look very similar to the way we deploy the Design System, although we may want to explore using CloudFoundry's native rolling app deployments feature, as we have with the Prototype Kit training docs.

We should follow PaaS guidance on deploying an app to production.

This does not include setting up the cdn-route nor the service domain – this will be covered by a separate issue.

Dependencies

• Set up continuous integration #5

Done when…

• Decide which PaaS credentials and space should be used to deploy
• Documentation deployed to a cloudapps.digital domain
• Updates to documentation deployed automatically as they are merged to the master branch
• Updates to other branches do not trigger a deploy to the live site

Publish GOV.UK Frontend sass docs into tech docs format

What

Publish the Sassdocs from GOV.UK Frontend

Why

We know it's not perfect but it's helpful for our users. A few users know about the unofficial https://govuk-frontend-review.herokuapp.com/docs/ and we want to make it official for people to use.

Who needs to know about this

Mark G, Developers, Chris?

Further detail

A spike has been done to see if it's possible and it is. We want to clean this work up.

Additional spike: #14

Depends on

• A production tech docs instance, currently the prototype exists at: https://github.com/alphagov/govuk-frontend-docs

Done when

• Add functionality to output sassdocs into tech docs format.
  • GitHub link should refer to current package tag rather than master
• Add tests to ensure output is correct
• Optional: Add functionality to allow for blocks in warning_text helper.

Future GOV.UK Frontend specific improvements

These are improvements to the Sass docs themselves in the main repository.

• No 'general' section for main-wrapper.

Improve 'Install from dist' documentation

What

We need to improve our 'Install from dist' documentation

Why

It was one of the pieces of documentation we migrated to the Tech Docs Template without improvement, because we prioritised the npm install guide.

We know that many users may be confused by the use of dist in the title. There are also other improvements we can make to ensure the documentation is clear and concise.

Who needs to know

Developers

Done when

• This has been published
• alphagov/govuk-frontend#1818 has been published

Improve more of the TDT developer docs

What

• Decide which (if any) docs we can prioritise for improvement during Q1
• Improve the docs

Why

We prioritised improving some of Frontend's developer documentation before we moved it to the Tech Docs Template, but the remaining documentation needs improving too.

Candidates are:

• Install from dist
• Support Internet Explorer 8
• Sass API reference

Mark LibSass as deprecated in 'Installing with npm' documentation

What

In 'Install with Node.js package manager (npm)' we say:

Install either:

• LibSass - version 3.3.0 or higher
• Dart Sass - version 1.0.0 or higher

GOV.UK Frontend also works with Ruby Sass version 3.4.0 or higher, but we recommend you do not use Ruby Sass because it’s been deprecated.

Since writing this, LibSass has now also been deprecated:

All of this means that it's time to start directing users away from LibSass, standardizing on Dart Sass as the primary (and for now the only) recommended language implementation.

We should update our own documentation to prefer Dart Sass over the two deprecated libraries. We will still continue to fully support LibSass for a while yet (likely until we migrate to the Sass module system), in the same way we continue to support Ruby Sass.

Why

For new projects it makes sense to recommend Dart Sass over the other implementations wherever possible, especially as we intend to migrate to the Sass module system at some point in the future, which currently would require users to migrate to Dart Sass.

Done when…

• Guidance drafted to recommend Dart Sass over the deprecated LibSass and Ruby Sass libraries, whilst making it clear that the deprecated libraries are still supported for the time being
• Guidance 2i'ed
• Updated guidance published

Improve navigation within Sass API Reference

What

Decide:

• whether to add a table of contents to each section in Sass API Reference
• on a rationale for ordering section contents

Why

Our Sass API reference has a lefthand nav panel. However, there is no nav aid for the contents of the H3-headed sections (like Assets, Colours, Links and so on). So, for example, users looking for a specific mixin might have to jump around in the Links section until they can find it.

It might save users some labour if we added a table of contents, with links, near the top of each section. However, we already have several levels of navigation and hierarchy, with the left hand nav's top-level outline of the page structure. So, we need to work out the best way to help users navigate through the page.

Also, it's unclear why the sections are ordered as they currently are. If they displayed in alphabetical order, that might help users to locate content more easily. However, there may also be areas where we want to display contents in a certain order. For example, link styles, where it makes sense to introduce 'common' mixins first, and then 'style' mixins.

Who needs to know about this

Designers, Developers, Technical Writer, User Researcher

Done when we

• carry out any user research required
• decide on options for improving navigability and reordering section contents
• implement agreed changes

Add guidance on what `Cache-Control` headers should be used on assets

The example is specifically related to fonts, but is the same principle for all assets.

An issue raised by Ed on the x-gov channel where unstyled text is being seen between page loads. This is Arial to Transport changing over. In theory this shouldn't be occurring because by this point the font is already in the cache. But an assets actual usage is dictated by the Cache-Control headers. For example, if a font is already in a browser cache but it has Cache-Control: max-age=0 set, looking at the examples in the MDN docs:

Specifying no-cache or max-age=0 indicates that clients can cache a resource and must revalidate each time before using it. This means HTTP request occurs each time, but it can skip downloading HTTP body if the content is valid.

This revalidation is blocking the browser from using the font, even though it is in the cache. It takes 1-RTT (round trip time) from server to browser before the browser is allowed to use the font. This could be 100ms+ on poor performing servers / or users on poor connections.

We should add guidance on setting long-life Cache-Control headers for assets. For example, 1 year is set on fonts served from www.gov.uk:

cache-control: max-age=315360000

If it is that we want this revalidation to occur we can use the stale-while-revalidate directive. But as these font files have changed only once in many years, it really isn't needed.

Update IE8 content to specify when users need to support it

What

We need to add a sentence to say users should follow the steps if they've decided to support Internet Explorer 8 (IE8).

Why

The current content makes it sound like users have to support IE8, whether or not they've decided to.

Who needs to know about this

@36degrees, @EoinShaughnessy, @hannalaakso, @vanitabarrett

Done when

• Eoin drafts update
• Devs review and approve update
• Update clears 2i

Document new fixtures hidden property

What

• Update the example in 'Test if your HTML matches GOV.UK Frontend' to include the hidden property
• Add hidden to the list of properties under the example, with an appropriate description

Why

In 'Test if your HTML matches GOV.UK Frontend', we provide a description of the fixtures found in a components fixtures.json.

alphagov/govuk-frontend#2031 adds the hidden property to the objects in the fixtures list, so we need to update the documentation appropriately.

Who needs to know about this

@EoinShaughnessy, @hannalaakso, @36degrees

Done when

• Example updated
• List of properties updated
• Changes 2i'ed

Include default values for settings in the Sass API reference

What

Document the default values for settings within the Sass API reference

Why

As a user configuring GOV.UK Frontend, knowing what the default value for a setting is helps me understand how that setting is used, and whether I need to change it.

Add accessibility information (to Design System accessibility statement)

We need to add accessibility information about this documentation to the Design System accessibility statement by 23 September 2020, explaining how/whether this documentation meets WCAG 2.1.

Done when

• (Dependency) Tech Docs Template (TDT) has been audited by DAC, and accessibility statement added about any design issues with TDT generally
• We've added lines to the Design System accessibility statement about known accessibility issues in Frontend docs, and plans to fix them
• We've added the missing date.

Update frontend docs to use GOV.UK Frontend v3.10.1

What

Once GOV.UK Frontend 3.10.1 has been released, update the frontend docs to use it.

Why

So that the frontend docs use the latest release of GOV.UK Frontend.

Set up continuous integration

What

Set up continuous integration for the GOV.UK Frontend Docs.

Why

As maintainers, we want to be confident that the tech docs will continue to build correctly when approving and merging pull requests against the documentation.

Further details

This will be very similar to the way that we run CI on the Design System, so we can use that as a basis.

This does not include continuously deploying the master branch, which will be a separate issue.

Done when…

• The build succeeds if the site can be built successfully
• The build fails if the site cannot be built successfully
• The build status is reported to GitHub
• 'Travis CI - Pull Request' is configured as a required status check, preventing merging if the tests fail

Add a broken link checker

What

We should test our generated markup for broken links.

Why

To ensure that any broken links are flagged up as part of the build.

Extra detail

We should probably solve for this the tech docs template rather than just this repo

Done when…

• We've added a broken link checker which fails the build if broken links are found

Add cookie consent functions in the frontend docs

Follows on from alphagov/govuk-design-system#1614

What

In alphagov/govuk-design-system#1614, we added a set of cookie consent functions to the design system. We need to add the same set of functions to the frontend docs.

Why

We will need this set of functions to hook into when we add the cookie banner and cookie preferences form.

Who needs to know about this

Developers

Done when

• We have functions for the main cookie banner/form behaviour, e.g: accepting and rejecting cookies; deleting cookies (see list in design system card)
• Tests for all of the cookie consent functions
• Consent cookie can be shared with design system site
• Functions should match what's in the design system

Use PaaS supplied buildpack

What

When we set the Design System up, PaaS did not support the nginx buildpack, so we had to reference the buildpack using its GitHub URL, pinning to a specific version.

PaaS now provide an nginx buildpack, so we can now use that instead.

Why

This means whenever PaaS update their buildpacks we'll automatically use the latest version when we next deploy.

Further detail

We did this with the Design System in alphagov/govuk-design-system#1345

Update the Frontend Docs to use GOV.UK Frontend v3.13.0

What

Once GOV.UK Frontend 3.13.0 has been released, update the Frontend Docs to use it.

Why

So that the Frontend Docs reflects the latest release of GOV.UK Frontend.

Who needs to know about this

Developers

Done when

• Frontend Docs is using version 3.13.0

Then…

• Merge #131

Fix continuous deployment of Frontend Docs

What

Fix continuous deployment of the GOV.UK Frontend docs, which is currently broken.

Why

The deploy stage is failing on the master branch, which means changes are no longer being deployed automatically.

Starting deployment for app govuk-frontend-docs in org govuk-design-system / space frontend-docs as [email protected]...
OK
Waiting for app to start...
Start app timeout
TIP: Application must be listening on the right port. Instead of hard coding the port, use the $PORT environment variable.
Use 'cf logs govuk-frontend-docs --recent' for more information
FAILED
Script failed with status 1

We think this is because we're still using the v3 prefixed commands to deploy:

govuk-frontend-docs/bin/deploy-travis

Lines 11 to 14 in a7f28e4

	cf v3-create-app $APP_NAME
	cf v3-apply-manifest -f manifest.yml
	# Deploy using CloudFoundry zero-downtime push
	cf v3-zdt-push $APP_NAME -p $APP_PATH --wait-for-deploy-complete

And, roughly:

• v3- commands were experimental, while they worked on the API
• v7 CLI came out, and uses the v3 API in a not-experimental way (i.e. it’s supported properly)
• The v3- commands weren’t updated to work with newer versions of the API

So we think the solution is to upgrade to the V7 version of the CLI, and use non-prefixed commands.

Further details

The same issue came up in the learn-to-code repo, and was fixed by the changes in alphagov/learn-to-code#40.

It might make sense to do #89 at the same time.

Set up 404 and generic error pages

What

Users should see a 404 page on trying to access a non-existent page or a generic error page with other errors

Why

To avoid confusion

Who needs to know about this

Devs

Done when

• A 404 page is shown when accessing /potato

Update the Frontend Docs to use GOV.UK Frontend v3.9.0

What

Once GOV.UK Frontend 3.9.0 has been released, update the Frontend docs to use it.

Why

So that the documentation reflects the latest release of GOV.UK Frontend.

Fix accessibility issues by updating the govuk_tech_docs gem to 2.2.0 [before 31 March]

What

First, update the govuk_tech_docs gem from 2.1.0 to 2.2.0.

Change log

2.2.0

Accessibility Fixes

• #205: Improve table of contents accessibility
• #209: Some search and keyboard navigation updates
• #210: Stop linking images to new tabs
• #214: Implement row level table headings to allow accessible tables with row headings
• #215: Add tabindex and focus states to code blocks

Docs

• #206: Remove tdt docs content from readme file

2.1.1

Fixes

We’ve made fixes in the following pull requests:

• #199: Fix page expiry box link colours (hover and focus)

Ruby version bump

We've updated the Ruby version supported:

• #201: Bump ruby to 2.7.2

Then identify and fix any tables which require row level headers.

There is a single table in migrating from legacy products, and multiple tables in the Sass API reference docs.

Why

Version 2.2.0 of the tech docs gem is now live and incorporates fixes to a number of accessibility issues in the technical documentation template which are referenced in our accessibility statement:

• Some tables in content do not have column row headers when needed.
• Users cannot tab to code examples to scroll them using the keyboard.
• The search field and the ‘Hide table of contents’ button are not placed logically in the focus order.
• Users can focus elements that are hidden visually behind other content, for example when using the search field.
• Images link to a new tab without telling users, and do not have link text.

Done when

• Gem updated
• Tables include row headers where required
• Verified that the issues listed in the accessibility statement are fixed (see guidance)

Fix accessibility issues in Frontend docs

What

Audit and fix accessibility issues in GOV.UK Frontend docs, and publish accessibility statement content.

Why

This is part of an overall accessibility audit of our Tech Docs Template technical documentation across GDS. It's being led by Mark and Jon Glassman.

We want to publish accessibility statements (or accessibility notes in wider product accessibility statements) for Tech Docs Template technical documentation by September.

Who needs to know

Tim, developers

Done when

• We've audited Frontend docs for accessibility issues
• We've identified which issues to fix
• We've fixed the issues

Rename the default branch to `main`

The default branch for this repository will soon be renamed from master - a potentially offensive term - to main. Many other GitHub communities are also renaming their default branches. To learn more about this welcome news, check out Git’s statement about why branch renaming matters.

You may need to make changes if you have a local copy or fork of this repository. You can view our guidance on this Github issue.

Restrict access to cloudapps.digital domain

What

We don't want users or search engines accessing the cloudapps site

Why

To avoid confusion or search ranking

Who needs to know about this

Devs

Done when

• You get prompted for authorisation when trying to access the cloudapps site

Update the Frontend Docs to use GOV.UK Frontend v3.12.0

What

Once GOV.UK Frontend 3.12.0 has been released, update the Frontend Docs to use it so that the Sass API reference includes the new mixins.

Why

So that the Frontend Docs reflects the latest release of GOV.UK Frontend.

Who needs to know about this

Developers

Done when

• Frontend Docs is using version 3.12.0
• Sass API reference includes documentation for the new link style mixins

Ensure Netlify previews are not indexable

What

We need to make sure that Netlify previews are not indexable by search engines.

Why

So that users aren't confused by findings previews of PRs

Further details

In Design System we conditionally include the noindex tag if there is no Travis branch environment variable.

Done when

• We've conditionally set the prevent_indexing option depending on environment variables

Set up CDN for Frontend docs domain

What

We need to set up a cdn-route service on PaaS that we can use for the service domain. We then need to add a DNS record for the frontend docs sub domain that points to it.

Why

So that we can use our service domain with PaaS.

Done when

• Follow steps in Paas Docs

Update README

The instructions are a bit verbose and are mainly for when you start a new tech docs gem. Should include clear steps to get this project running locally.

Update the Frontend Docs to use GOV.UK Frontend v3.7.0

What

Once GOV.UK Frontend 3.7.0 has been released, update the Design System to use it.

Why

So that the documentation reflects the latest release of GOV.UK Frontend.

Enable Ruby linting for project

I think my Ruby has been inconsistent, for example string usage, so would be good to add our regular linting and tidy it up.

Gets Tech Docs Template docs content ready for live

What

We need to finish up the docs content so it's ready for publishing live.

Why

It's a dependency for moving the docs in Tech Docs Template format to live at the end of this quarter.

Who needs to know

Mark, devs

Done when

• Updated all docs to match current live versions
• Updated links that point to research version of DS/Prototype Kit/Frontend repo (including footer)
• Footer links and front page have been reviewed by team
• Footer links and front page have been reviewed by tech writers

Set up LogIt logging

What

We should send our logs to Logit so that we can use Kabana to generate reports.

Why

We already do this for the Design System website so we should be consistent with our logging.

Who needs to know about this

Devs, Kelly

Done when

• Logit receives logs
• Set up some visualisations in Kabana (similar to the Design System website)

Add cookie banner to frontend docs

What

Add the cookie banner component to all pages in the design system.
Hook into the cookie consent functions so that users can accept or reject cookies

This is likely to look different to alphagov/govuk-design-system#1618 as the frontend docs uses the tech docs template. We should look into if it's possible to add functionality to the tech docs template to display a cookie banner without having to inject it using JavaScript.

Why

We need to give users the choice to accept or reject cookies.

Who needs to know about this

Developers

Done when

• Work in the feature branch
• Consider Cumulative Layout Shift in the implementation
• Explore expanding tech docs template functionality to allow displaying a cookie banner
• Add the cookie banner component to all pages in the frontend docs, using the drafted text
• Only show the cookie banner if a consent cookie isn't present and/or if it's not an up-to-date version
• Hook into the cookie consent functions to allow users to accept cookies
• Hook into the cookie consent functions to allow users to reject cookies
• Show a confirmation banner when a user has selected a preference
• Allow users to hide the confirmation banner
• Implement a no-JS solution
• Hide the banner when on the cookie page?

Add Google Tag Manager code to the frontend docs

Similar to alphagov/govuk-design-system#1616

What

Add Google Tag Manager code snippet to the frontend docs

We should be ok to merge these changes as the Google Tag Manager code relies on consent being given for analytics cookies, which a user can't do if we add this before we add the cookie banner.

Why

We need to add the Google Tag Manager code to the frontend docs so we can use analytics to track pageviews and events.

Who needs to know about this

Developers; Performance Analyst

Done when

• Talk to Sara about what code needs to be added (get the ID)
• Google Tag Manager code should only be loaded when consent has been given for analytics cookies
• Load GTM and trigger a pageview event as soon as analytics cookies have been accepted - don't wait for the next pageview
• Tests for the above functionality

Add Google Analytics tracking to the frontend docs site

What

This work looks at adding Google Tag Manager and Google Analytics on frontend.design-system.service.gov.uk. This follows on from work to add it to the design system: alphagov/govuk-design-system#1610. Ideally this uses the same cookie and we make use of sub-domain consent.

Why

We want to include GA on tracking back on the Frontend Docs site so that we can better understand how our users are engaging with the website. We can then use this data to learn and improve more about the Frontend Docs.

Who needs to know about this

Developers, Performance Analyst, Content Designer

Done when

Tasks

Beta Give feedback

1. Decide approach for sub-domain consent govuk-design-system#1613
   analytics performance +2
2. How does this affect our GTM setup and deployment plan?
3. Tweak existing govuk-design-system cookie consent functions to handle sub-domain consent
4. Add cookie consent functions in the frontend docs #118
   +0
5. Add Google Tag Manager code to the frontend docs #119
   +0
6. https://github.com/alphagov/govuk-design-system/issues/1619
7. Change content within the design system cookie page
8. Change content within the design system cookie banner
9. Reset the banner for users if switching from design-system only consent to sub-domain consent