alphagov / tech-docs-template

A template for building technical documentation with a GOV.UK style

Tech Docs Template

The Tech Docs Template is a Middleman template that you can use to build technical documentation using a GOV.UK style.

This repo is the template used to generate new sites. The generated site uses HTML, CSS, JS and images from the tech docs gem.

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.

Contribute

👉 Find out how to contribute.

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.

tech-docs-template's Issues

Use WAI-ARIA dialog role for search results modal

This was recommended during the accessibility clinic. More info here: https://www.w3.org/TR/wai-aria-practices/#dialog_modal

Tables don't render properly when followed directly by heading with no characters between

Tables do not render properly when they are followed directly by a heading with no characters in between them. The table must have at least one character on a new line between it and the heading that follows in order for the table to work. With this error, the heading breaks as well.

Back button breaks without in-page-navigation

We turned off in-page-navigation because it was causing us problems and found out that without it the back button does not work for navigating between anchors.

Options for adding search

I've been thinking how to add search. Have come up with 3 or so options.

1. Javascript

We could use lunrjs to do search. It's a lightweight solr-clone in JS.

It would probably work by generating a JSON lunr database on each build. We'd create a frontend that uses lunr to show the search results.

I think this is what https://github.com/manastech/middleman-search is trying to do.

Downsides:

• It's a lot of javascript that needs to be executed during build phase. You'd need node installed or something?
• It's probably not accessible, doesn't work without Javascript

2. External service - push

On each build we create a JSON blob with all the content. This is then POSTed to the external service during deploy. This service indexes it, probably in elasticsearch.

If a user searches they'd be redirected to this search service, which serves results. We can have a sprinkle of JS on top that does auto-suggestion and such.

Downsides:

• This needs authentication, otherwise anybody can post

3. External service - pull

Same as above, but instead of sending the JSON, the service scrapes the HTML of the site. Or pulls in the JSON.

After each deploy, the deploy script would only ping the search service to tell it to refresh.

This looks like what https://www.algolia.com does (used by https://middlemanapp.com)

Downsides:

• Site may not be in sync with what's deployed, because there's lag between deploy & the indexer

Thoughts?

Support for monospaced headings

#95 made some changes to the typography that causes headings with a monospace font to be displayed smaller. We use monospaced headings often in API docs like https://docs.publishing.service.gov.uk/apis/publishing-api/api.html.

Before

After

Template - add footer for owner/date information

Owner/date information. GOV.UK dev docs have introduced a footer to indicate the owner of the content and when it was last updated - yet to be tested, but nice feature.

Logo image has no alt attribute

The code:
<img class="govuk-logo__printable-crown" src="/images/gov.uk_logotype_crown_invert_trans.png" height="32" width="36" style="">

From Siteimprove:

The image does not have an 'alt' attribute (alt="").

It’s important all images have the attribute for alternative text regardless of whether an alternative text is added.

A screen reader knows how to handle both an empty alt attribute and one with a text. If there is no attribute some screen readers will compensate and read the path to the image instead, which will often give no value to the end user.

Implement support for non-JS users

Why

We've accidentally discovered that this template doesn't render well if the JavaScript is disabled.

Following this blog post:

• How many people are missing out on JavaScript enhancement? by Peter Herlihy

we believe it should be resolved in order to keep up with Using progressive enhancement.

Be able to configure the GA tracking event category

The event category is set to "SM Technical Documentation"

tech-docs-template/template/source/javascripts/_analytics.js

Line 10 in ae16d39

'SM Technical Documentation', // Event Category

but it would be good if this could be configured. Perhaps in the config/tech-docs.yml file or perhaps from a <meta> tag.

Create 'Print' function on each section

A finding from user research is that people are interested in printing the document as a pdf. However, they would only want to print out selected sections.

Navigation - restrict a heading from appearing in the left hand nav

We specify the level of headings that appear in the left hand nav of a site through the tech-doc.yaml config file.

Is it possible to add a feature that allows you to restrict a heading from appearing in the left hand nav?

For example, if you specify that h1, h2, and h3 headings appear in the nav, but only want certain h3's to appear. Having them all appear would make the left hand nav too long and user-unfriendly.

Linking to anchors not displayed on ToC doesn't work

Problem:

Trying to follow a link to the anchor of a section that is below the level which is displayed on the left-hand table of contents doesn't work. You are taken to the beginning of the docs instead.

For example:
https://paas-tech-docs.cloudapps.digital/#ip-restrictions should be a valid link. But it's a level 3 header and these docs are configured to show only down to level 2. So following the link doesn't work.

Fix:
Linking to anchors should always work, even if they are not shown on the ToC.

Question about adding Search function for tech-doc-template

Hi,
I'm a Product Manager working over at Ministry of Justice on our Cloud Platform. As part of our new platform we are creating a guide for users based on the tech-docs-template which helps them interact with our platform.

This first iteration works on the basis that users work through the step by step guidance to build their non-production environment and then build, test and deploy their product (or the Test App). They can then add the resources we have made available e.g. Postgres, secrets, S3 etc.

However, the existing guide doesn't allow the users to search for or skip to specifics. You have to work through the detail or have sufficient context to know where some guidance may exists within the guide.

We were wondering what the scope is for adding some search facility to allow users to interact with the guidance in a different way to get more value from it.

Grateful for any suggestions. Many thanks.

Visible focus area of collapsible navigation items are wider than the clickable area

When tabbing through collapsible navigation items:

The visible focus area of the navigation item is wide enough to include the collapsible button, for a user that is tabbing through the page, it can be unclear that there are two different actions when selecting the navigation item (visits a new page) and the collapsible button (toggles the sub-items)

Direct link with fragment doesn't scroll to anchor

It's scrolling when you click on a navigation link but not when you paste the URL directly into the address bar.

e.g.

http://127.0.0.1:4567/#scaling-apps

Width of code blocks

Make sure horizontal scrollbar is always shown on Macs. Investigate button to expand content across the full screen.

Improve distinction between menu items

Cosmetic suggestion.

As well as indenting, it would be great to help distinguish between h2 and h3s in long menus. Perhaps bold or something else? I've attached a pic of the long registers docs menu.

Output - PDF output required for some manuals which can't be published openly

Split pages for long documents

User research on the Verify Tech Guide shows that users get to the end of a procedure and carry on scrolling down whereas it would be more appropriate to stop and go to another place in the document.
The process of onboarding with Verify isn't linear. You have to do the same thing in different environments so there is a degree of flitting backwards and forwards in the doc. Users miss this because it's one long page. It would be good to chunk information.

Last list anchors broken on mobile / tablet viewport

Note: Copied this issue from the GDS Way.

To reproduce:

• Goto: https://gds-way.cloudapps.digital/#standards
• Shrink the viewport down to approx 760px
• Try clicking on "storing source code" link
• Link not clickable due to following headings negative margin causing an overlap.

Issue caused here

h3, h4, h5, h6 {
    @include heading-offset($gutter);
  }

Proposed fix:

1. Either remove usage of the mixin in this case and add specific styling manually (less padding, no negative margin)
2. Continue to use the mixin but add an override after it's usage

Option 1 seems like the cleanest to me with minimal impact.

header_footer_only doesn't include footer

The header_and_footer_only template doesn't actually include the footer.

Most of the pages on https://docs.publishing.service.gov.uk use that layout, so the footer is only shown on our guides page.

Multi-page format - support multiple pages

In recent user testing, the single page format didn't always test well. With further testing, it could be beneficial to support multiple pages. As an example, see the GOV.UK developers or GDS Way implementation of the template.

Google indexes heading anchor alt-text

Google apparently runs Javascript and indexes the "Link to here" in the titles.

https://www.google.co.uk/search?q=site%3Adocs.publishing.service.gov.uk

Maintain the scroll position of the sidebar navigation across new pages

One feedback I received when testing the new multi page navigation was that the scroll position of the sidebar navigation jumps around when you're clicking into different pages. This can disorient people who are browsing content on several pages, as they have to adjust the scroll position to understand their location in the IA.

Something like turbolinks/turbolinks would work, and it would probably speed up page load time. We could also store the scroll position in the browser.

Presentation of inline monospace font

Inline monospace does not stand out enough. Investigate different colour/font weight combo (mkdocs and other systems use red).

Update JS/CSS version

update it to the latest JS/CSS version

Package template as a gem

One of the challenges in making use of the tech docs template long term and for considering the addition of new features to tech docs is that the tool is packaged as a starting point for your microsite that you diverge from rather than a dependency that you manage. It would be easier to evolve with tech-docs-template if it was packaged in the form of a gem, rather than a middleman template.
Feedback from @kevindew

Expanded nav is too long with real content

Need to either:

1. Make levels shown configurable (for example cuts off at h2)
2. Implement expand/collapse.

HTTP with query parameters not rendering properly

This is some Markdown:

```http
GET /records/KIN/entries/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE

Below the bullet point in the image below (as an example) is how it should render, and it does for most of the content:

... except for similar content which has query parameters (I am assuming this is what's causing the issue), e.g.:

... which has this Markdown:

```http
GET /records/local-authority-type/CTY/?page-index=1&page-size=3 HTTP/1.1 
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE

You can see this live at https://docs.registers.service.gov.uk/

Repo is https://github.com/alphagov/registers-tech-docs

Google analytics isn't available on sections

It's useful to have reliable Google analytics on the different sections in a document so we can see which bits of content are working and which aren't. Google analytics will pick up clicks in the navigation panel but this won't give a reliable picture if we're working on the assumption that users will scroll through the doc and use the Ctrl+F function to find content.

Back button doesn't work as expected after following a nav link or anchor

If you view one section then click a link on nav or an anchor, then click back, you are not taken to the previous section, but to the previous site you were browsing.

Middleman `ruby` process hangs randomly

Middleman hangs on me when I run bundle exec middleman server at seemingly random times. I can't look at http://localhost:4567/ (I'm using the default port) and I can't exit out of the process on the CLI.

I can identify the PID and kill -9 it then rerun bundle exec middleman server, with the same background processes running, and then it'll work, so there doesn't appear to be any pattern.

It might well be my setup but this wasn't happening before the recent updates.

Took a sample of processes (middleman_hang.txt):
middleman_hang.txt

API Explorer - add functionality

Research into documentation and formats ongoing, including whether an API explorer would help/hinder register adoption.

Compatibility testing

Anecdotally we know the template has not been tested thoroughly on Windows

Sluggish scroll

We've recently activated the in-page-navigation module on GOV.UK tech docs:

https://docs.publishing.service.gov.uk/#content

Since then it feels scrolling feels a bit sluggish. Is that fixable?

Tables render incorrectly

Submitted by Marian Foley.

Example added:

"line of text

| This | is | a | table |
| some | words | go | here |

line of text

I also tried with a heading line (tried a line of | --- | and a line of | :--- | but neither worked).

This is a table that renders fine on Whitehall publisher. I was wondering if the dev team could check that it works the same in the tech docs tool.

URL: https://www.gov.uk/guidance/set-up-government-email-services-securely

page in whitehall publisher: https://whitehall-admin.publishing.service.gov.uk/government/admin/detailed-guides/745834"

Use the file-url helper function from the frontend toolkit for background images

In some places, image paths use url() and in others image-url().

Would it be possible to use the url-helpers function from the frontend toolkit?

For example:

background-image: file-url('[email protected]');

This will output image-url for your project, but will allow other projects consuming this to override $path to specify the location of their image assets.

Can't link to an anchor within the docs from header links

I wanted the Get Started link in the header to link to a section within the docs. I used this:

header_links:
About: https://www.cloud.service.gov.uk
Get Started: #getting-started
...

and restarted middleman. The resulting HTML output is:

Get Started

In some cases, the header links will need to point to an anchor on the current page, so important to fix this.

Searching - missing search functionality

Update to gov.uk frontend

This project currently includes alphagov/govuk_frontend_toolkit which has now been replaced by alphagov/govuk-frontend.

See this page for instructions: https://design-system.service.gov.uk/get-started/updating-your-code/

This would help support #151

Links - Anchor links

1 page issue - there are a number of items listed on this sheet that could be resolved if we moved away from a one-page format and introduced search functionality (I mention this because my understanding is that we decided to use the one page format partly in response to not having a 'proper' way to search through content). I think this issue might also be resolved that way as there would be less of a need to use anchors if content didn't only live on one long page.

Searching -searching with context is hard

Headings - index.html.md.rb & H1 heading

If your first file in your index.html.md.rb file does not have an H1 heading, it breaks the tool. If you were, for example, to copy some pre-existing markdown files into the documentation folder and they do not have any H1s, and then remove the pre-existing index file from the index.html.md.erb file, then this would happen.

Initial fragment not stored in the browser history

I clicked this link: https://govukpay-docs.cloudapps.digital/#contribute
Then I scrolled up and down, and the fragment in the URL changed.

I was expecting the back button to take me back to where I entered the docs, but the browser showed no page history.

I'm using Chrome Version 59.0.3071.115 (Official Build) (64-bit)

It seems like there is some code to handle this, but I didn't see anything obviously wrong with it https://github.com/alphagov/tech-docs-template/blob/master/template/source/javascripts/_modules/in-page-navigation.js#L43

Scrolling out of sync

If you scroll the main content, the nav doesn't scroll. The highlight moves up and down, but the actual nav doesn't scroll. Need to find a way to keep nav in sync with main viewport.

Navigation - Left-hand nav links sometimes unclear

Left-hand nav links sometimes unclear. Difficult to see where you are in the document.

Scrollbar not shown for nav on some Macs

Always show vertical scrollbar for Mac browsers.

Collapsible action buttons do not refer to the element they affect

The WAI-ARIA standard specifies an aria-controls attribute.

We can add this to the collapsible action buttons, so certain user agents (only JAWS, I think) can communicate the relationship between the button and the navigation sub items that it toggles.

Reloading browser ignores any anchors in URL in Chrome

If you navigate to a section so that there's an anchor in the URL e.g. http://localhost:4567/#pushing-an-app-to-cloud-foundry-using-jenkins then refresh the browser, the anchor is ignored and you go to the top of the page, even if the URL is the same.

This does not happen with Safari or Firefox, and it doesn't happen if you go directly to the anchor (e.g. by pasting into browser addressbar or following a link). Low priority but potentially confusing for tech writers or docs readers.

Collapsible button icons aren't visible when browsers are overriding background colour

Firefox allows users to specify colour style overrides, one side effect of this is that icons tends to disappear. I'm guessing that's because they've been set using CSS background-image. More on overriding colour styles information here.

I'm not sure how to fix this yet, but I heard that @NickColley has been fix these issues in the design system, he might have some advice.