MHCLG Funding Data Standards Technical Documentation

This project is an alpha/proof of concept site to publish the processes and technical documentation (including data standard schemas) for the Ministry of Housing, Community's and Local Government's (MHCLG) Funding Data Standards.

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.

While the Tech Docs Template this site has been based on has now been archived, the documentation guidance is still available on their GitHub Repo, or a summarised guide has been published by Mat Moore. The Tech Docs Ruby gem that controls the styling and rendering is still being updated and maintained, and is used by GOV.UK services for API and technical documentation, including:

• GOV.UK developer docs
• GOV.UK Notify documentation
• GOV.UK Pay documentation
• GDS Way
• MoJ Cloud Platform User Guide
• Content API documentation

Before you start

To use this project, you need to install:

• Ruby (we'd suggest installing Ruby via RBenv or RVM)
• Middleman

Making changes

To make changes to the documentation, 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

You can use Markdown and HTML to generate different content type. See the guidance published by Mat Moore for more specifics on adding styling in Markdown and HTML.

You can structure the site pages using subfolders and index.html.md.erb files in their roots.

You can change the site config by editing the config/tech-docs.yml file.

Updating JSON Schemas

Each data standard page has a JSON schema section so that implementers and stakeholders can see the full list of data points being collected, their data types, suggested validation rules and how the data standards are linked.

For developer ease (syntax checks etc.) the schemas and any referenced schemas which are not part of a main data standard are saved as JSON schema files in the schemas folder. They should be updated here and then the full schema can be copied to the relevant data standard or referenced schema page to ensure they remain consistent.

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.

Publish

Merges to the main branch on the Funding Service Data Standards will trigger a GitHub workflow which will build the HTML pages, compile them into a tar artifact and deploy this to GitHub pages.

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

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.