Analytical Platform user guidance

The Analytical Platform user guidance uses the Tech Docs Template. To find out more about how to use this template, see the Tech Docs Template documentation.

Build and deployment process

The user guidance is built and deployed using CircleCI.

When you create a PR, CircleCI will check that your changes build correctly.

When you merge a PR into main, CircleCI will build the user guidance and deploy the output files to a bucket in Amazon S3. The user guidance is then served at user-guidance.services.alpha.mojanalytics.xyz through a content delivey network (CDN) provided by Amazon CloudFront.

Contribute to the guidance

To make changes to the documentation for the Tech Docs Template website, edit files in the source folder of the repository.

Structure

The .html.md.erb files control the structure of the guidance. These files support content in:

Markdown
HTML
Ruby

They are generally of the form:

---
title: Page title
weight: 10
last_reviewed_on: YYYY-MM-DD
review_in: 2 years
show_expiry: true
---

<%= partial 'documentation/page-title' %>

The weight of a page controls its position in the guidance. Pages are sorted according to increasing weight. For example, a page with a weight of 50 would appear after a page with a weight of 40.

When you review a page, you should update the last_reviewed_on date.

The guidance uses a multipage structure to nest content. To find out more about how to manage this structure, see the Build a multipage documentation site in the Tech Docs Template documentation.

Content

Page content is stored in .md files in the source/documentation folder of the repository.

To find out more about how to work with Markdown files, see the Change your content section of the Tech Docs Template documentation.

Style

When contributing to the user guidance, you should make sure that your changes:

are consistent with the Government Digital Service (GDS) style guide
meet government accessibility requirements as far as possible
follow the spelling and grammar conventions outlined in the Analytical Platform A to Z.

Preview your changes locally

To preview the guidance locally on an MoJ Digital and Technology MacBook, navigate to your project folder and run:

bundle exec middleman server

You can view the guidance 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, select ⌘+C.

If you make changes to the config/tech-docs.yml configuration file, you will need to restart the Middleman server 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.

Update dependencies

To update this repo's Ruby dependencies, run:

bundle update
bundle exec middleman server  # and quickly test it in your browser

Now commit the updated Gemfile.lock in a PR, as usual.

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.

Licence

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

learn2excel/user-guidance