alphagov / tdt-documentation

Documentation for the Tech docs template

Tech Docs Template Documentation

This repository was previously used to generate the documentation website for the Tech Docs Template. Following the decommissioning of PaaS that site is no longer live. The documentation remains available in this git repository, although it is no longer maintained.

Publishing changes

GitHub Actions automatically publishes changes merged into the main branch of this repository.

Code of conduct

Refer to the alphagov code of conduct.

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.

tdt-documentation's Issues

Documentation project

it is possibly confusing using using the term 'documentation project' to refer to both an instance of the tech doc template and managing the content within it.

The content should be clear on the difference between these two distinct things.

Add folder structure images for single and multipage sites

Generate a sitemap.xml file automatically

What should change

Adds logic to create a sitemap.xml file automatically from the source files, respecting the noindex page data setting.

Identifying a user need

Search engine optimisation and navigation support for a sitemap for documentation sites.

Add documentation on how to add authentication to your documentation site

What should change

Add documentation on how to add authentication to your documentation site. There are several options that may work, depending on the use case.

Identifying a user need

The use case that prompted this is the data community tech docs needing some authentication to protect some official / sensitive data source information.

Decide for wrapped vs non-wrapped lines and make consistent

A very minor (and existing) thing that'd be good to fix at some point but shouldn't block this – there's a mix of wrapped and non-wrapped lines within and across all the files. It'd be good to try and make it consistent at some point.

Issue brought up in thread: #108 (comment)

Add images for layouts in page frontmatter

Current published tech docs

This table does not have a clear user need. Depending on the user need, it might be worth doing examples at point of use (e.g. GitHub pages) rather than as a separate table.

What is the user need? For current publishers - see others' implementation - worth writing in as examples at point of use rather than separate table?

Also, this is not an exhaustive list, yet it reads like one. Should instead link to a GitHub query.

https://github.com/alphagov/tdt-documentation/blob/master/source/publish_project/current/index.html.md.erb

OpenAPI specification file with header markdown errors on site load

If you use an OpenAPI specification file in a tech doc and use a markdown header in a 'description' field, it errors when the site loads.

Error:

TypeError: no implicit conversion of nil into String
        /usr/local/lib/ruby/gems/2.7.0/gems/govuk_tech_docs-2.3.0/lib/govuk_tech_docs/table_of_contents/heading.rb:16:in `+'
        /usr/local/lib/ruby/gems/2.7.0/gems/govuk_tech_docs-2.3.0/lib/govuk_tech_docs/table_of_contents/heading.rb:16:in `href'
        /usr/local/lib/ruby/gems/2.7.0/gems/govuk_tech_docs-2.3.0/lib/govuk_tech_docs/table_of_contents/heading_tree_renderer.rb:23:in `render_tree'
        /usr/local/lib/ruby/gems/2.7.0/gems/govuk_tech_docs-2.3.0/lib/govuk_tech_docs/table_of_contents/heading_tree_renderer.rb:31:in `block in render_tree'
...

Example OAS file:

openapi: 3.0.0
info:
  title: my title
  version: "1.0"
  description: "# My markdown heading"
paths:
  /my-path:
    get:
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string

Note: If you remove the # prefix in the description value above the site load correctly.

Make this the canonical documentation site

We currently have the tech-docs-manual (live on github pages) and this site (tdt-documentation.london.cloudapps.digital).

It would be good to make this repo the single source of documentation, and archive the other one.

Todo

• Decide on the branding (#55)
• Fact check the docs by a developer
  • https://tdt-documentation.london.cloudapps.digital/install_macs.html - #56
  • https://tdt-documentation.london.cloudapps.digital/create_new_project.html - #57
• Make all GitHub repos link to the new docs (the link next to the description)
• Add links in the READMEs to the new docs
• Archive https://github.com/alphagov/tech-docs-manual
• Redirect https://alphagov.github.io/tech-docs-manual

Re: 'Prerequisites for Macs'

Problem with 'Prerequisites for Macs' (https://tdt-documentation.london.cloudapps.digital//install_macs.html)

sd-community@... email no longer exists.

Re: 'Support'

Problem with 'Support' (https://tdt-documentation.london.cloudapps.digital//support/)

This page mentions the CDDO tech writing team - not sure about the current status of this.

Add example for .../configure_project/frontmatter/#last-reviewed-on-and-review-in

Table formatting

Table formatting in https://tdt-documentation.london.cloudapps.digital/publish_project/current/#current-published-technical-documentation is buggy.

File on GitHub:
https://github.com/alphagov/tdt-documentation/blob/master/source/publish_project/current/index.html.md.erb.

Configuration options `collapsible_nav` & `max_toc_heading_level` don't seem to work

What did you do? (steps to reproduce)

In my existing tech-docs project, I changed 'max_toc_heading_level' from 2 to 3, and 'collapsible_nav' from true to false.

I then stopped and started the middleman server.

What happened? (actual results)

In my development environment, the config changes seemed to have no effect at all - the sidebar nav. showed the same items, both expanded and collapsed, as before, and the sidebar items were still collapsible.

What should have happened? (expected results)

I should have seen more items in the left-hand navigation sidebar table of contents, and the top-level items should not have been collapsible.

Remove markdown section

Remove markdown section and link out to markdown documentation in keeping with GOV.UK proposition.

Keep the documented bug about the table issues

White gap left under footer, on short pages

I've noticed that on short pages the grey footer appears so high up that there is a white patch left below it.

Maybe that's intentional, but I thought I'd query it, even though I'm no designer. I wonder if it looks better if the footer was moved to the bottom of the browser on these occasions.

My colleague added some CSS to achieve this on a fork: moj-analytical-services/tech-docs-gem@df52c27

Switch to a docker-based system for preview & build

The current instructions require people to install ruby and the gems before they can get started with tech docs.

IMO, a docker-based workflow would be more generally applicable (e.g. developers who have never used ruby are still fairly likely to know about docker, or to have it installed already).

The following files could be used as the basis of a preview & build workflow, without requiring users to have ruby installed locally:

https://github.com/ministryofjustice/cloud-platform-user-guide/blob/master/makefile
https://github.com/ministryofjustice/cloud-platform-user-guide/blob/master/Dockerfile

Internal vs external audience content

Some content is only suitable for GDS-internal audiences e.g. 2i training.

Remove this content or signpost that it is internal to GDS only.

Add content on using ERB in code blocks to the edit content page

Support link doesn't go anywhere

The support link in the header navigation links to the documentation's homepage.
If there is no support, the link should rather be removed.

link to GDS helpdesk seems broken

https://gdshelpdesk.digital.cabinet-office.gov.uk/helpdesk/WebObjects/Helpdesk.woa hangs

Re: 'Tech Docs Template'

Problem with 'Tech Docs Template' (https://tdt-documentation.london.cloudapps.digital//)

The link to "tech-docs-notifier" on this page is broken (404 error)

Broken links

These links are broken, I believe mostly since #97

From	To	Anchor Text
https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/not-expired-page.png
https://tdt-documentation.london.cloudapps.digital/create_project/single_page/	https://tdt-documentation.london.cloudapps.digital/create_project/single_page/create_new_project.html	Create the content files
https://tdt-documentation.london.cloudapps.digital/publish_project/push_repo/	https://tdt-documentation.london.cloudapps.digital/create_new_project.html	Create a new local documentation repo
https://tdt-documentation.london.cloudapps.digital//publish_project/push_repo/	https://tdt-documentation.london.cloudapps.digital/create_new_project.html	Create a new local documentation repo
https://tdt-documentation.london.cloudapps.digital/amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/amend_project/configuration/docs/frontmatter.md	setting old_paths in the frontmatter
https://tdt-documentation.london.cloudapps.digital/create_project/multipage/	https://tdt-documentation.london.cloudapps.digital/create_project/multipage/search.html	search feature
https://tdt-documentation.london.cloudapps.digital/create_project/single_page/	https://tdt-documentation.london.cloudapps.digital/create_project/single_page/single_page.html	add a partial line
https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/last-reviewed-only.png
https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital/review_project/page-expiry/expired-page.png
https://tdt-documentation.london.cloudapps.digital/create_project/single_page/	https://tdt-documentation.london.cloudapps.digital/create_project/single_page/content.html	Amend your content files
https://tdt-documentation.london.cloudapps.digital/amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital/amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital/amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital/frontmatter.html	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital//amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital//amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital//amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital//frontmatter.html	https://tdt-documentation.london.cloudapps.digital/page-expiry.html	documentation for page expiry
https://tdt-documentation.london.cloudapps.digital//create_project/single_page/	https://tdt-documentation.london.cloudapps.digital//create_project/single_page/single_page.html	add a partial line
https://tdt-documentation.london.cloudapps.digital//amend_project/configuration/	https://tdt-documentation.london.cloudapps.digital//amend_project/configuration/docs/frontmatter.md	setting old_paths in the frontmatter
https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/last-reviewed-only.png
https://tdt-documentation.london.cloudapps.digital//create_project/single_page/	https://tdt-documentation.london.cloudapps.digital//create_project/single_page/content.html	Amend your content files
https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/expired-page.png
https://tdt-documentation.london.cloudapps.digital//create_project/single_page/	https://tdt-documentation.london.cloudapps.digital//create_project/single_page/create_new_project.html	Create the content files
https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/	https://tdt-documentation.london.cloudapps.digital//review_project/page-expiry/not-expired-page.png
https://tdt-documentation.london.cloudapps.digital//create_project/multipage/	https://tdt-documentation.london.cloudapps.digital//create_project/multipage/search.html	search feature

Documentation hosting in GOV.UK PaaS

What should change

The documentation should be hosted somewhere other than GOV.UK PaaS, on a domain other than london.cloudapps.digital.

Identifying a user need

GOV.UK PaaS is being decommissioned imminently, at which point the current documentation website will go offline. For users who need to refer to the documentation beyond the PaaS switch-off setting up hosting elsewhere will meet that need.

Add content on deploying and hosting documentation on docker and heroku

Correct Ruby install guidance

What should change

The Get started page says users should install the most recent stable release of Ruby. But the TDT has only been tested up to 2.7.3, so users should install that instead.

Identifying a user need

We've seen people get errors when they try to install the TDT using later versions of Ruby.

Add docs on google tag manager

Enable user to hide/show the left-hand sidebar

A 'show/hide' feature which collapsed the left-hand sidebar would make it easier to read wide tables or diagrams.