Update preview instructions, spelling, and deprecated contact

.devcontainer/devcontainer.json

@@ -0,0 +1,15 @@
+{
+  "name": "Middleman Preview",
+
+  "image": "mcr.microsoft.com/devcontainers/ruby:3.3",
+
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20"
+    }
+  },
+
+  "forwardPorts": [4567],
+
+  "postCreateCommand": "bundle install && bundle exec middleman server"
+}

.github/actions/spelling/allow.txt

@@ -345,3 +345,7 @@ yamls
 yml
 zalando
 zeitwerk
+finops
+Codespaces
+Customisation
+devcontainers

.github/actions/spelling/expect.txt

@@ -19,6 +19,7 @@ corepack
 cpen
 dbdveha
 dependencycheck
+devcontainers
 DLRM
 DNAT
 dnc

Gemfile.lock

@@ -139,12 +139,12 @@ GEM
     middleman-syntax (3.2.0)
       middleman-core (>= 3.2)
       rouge (~> 3.2)
-    mini_portile2 (2.8.2)
+    mini_portile2 (2.8.9)
     minitest (5.19.0)
     multi_json (1.15.0)
     mutex_m (0.3.0)
-    nokogiri (1.13.10)
-      mini_portile2 (~> 2.8.0)
+    nokogiri (1.19.4)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     openapi3_parser (0.9.2)
       commonmarker (~> 0.17)
@@ -156,7 +156,7 @@ GEM
     parallel (1.23.0)
     parslet (2.0.0)
     public_suffix (5.0.1)
-    racc (1.7.0)
+    racc (1.8.1)
     rack (2.2.7)
     rack-livereload (0.3.17)
       rack

README.md

@@ -1,115 +1,80 @@
 # The HMCTS Way
 
-<a href="https://gitpod.io/#https://github.com/hmcts/hmcts.github.io">
-  <img
-    src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod"
-    alt="Contribute with Gitpod"
-  />
-</a>
+Source for [The HMCTS Way](https://hmcts.github.io) — technical documentation for engineering teams across HMCTS (His Majesty's Courts and Tribunals Service).
 
 ## Getting started
 
-To preview or build the website, there are two options.
+There are two ways to run this site locally: GitHub Codespaces (no setup required) or a local installation.
 
-### Gitpod
+### GitHub Codespaces
 
-Gitpod is the easiest way to develop on this repository; you will get a fresh automated dev environment without having to set anything up on your machine.
+GitHub Codespaces gives you a ready-to-use dev environment in your browser with no local setup needed. The dev container installs all dependencies automatically, this can take a few minutes on first load.
 
-Click the button below to get started:
+Once setup is complete, run `bundle exec middleman server` in the terminal, then open the site using the globe icon next to port 4567 in the **Ports** panel.
 
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/hmcts/hmcts.github.io)
+<img src="source/images/ports.png" alt="The VS Code Ports panel showing port 4567 forwarded for the Middleman preview server, with the Open in Browser icon highlighted" width="400">
 
 ### Local installation
 
-##### below instructions will need to be modified to accomodate non-admin laptops
-e.g.
-gem install -user-install bundler
-bundle install --path ~/.gem                     
+**Prerequisites:** macOS ships with an old system Ruby that won't work here. You need the version specified in [`.ruby-version`](.ruby-version), managed via [rbenv].
 
+**1. Install rbenv and the required Ruby version**
 
-Install Ruby with Rubygems, preferably with a [Ruby version manager][rvm],
-and the [Bundler gem][bundler].
+```bash
+brew install rbenv ruby-build
+echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
+source ~/.zshrc
+rbenv install        # reads the version from .ruby-version automatically
+rbenv rehash         # makes the new ruby commands available in your terminal
+```
 
-In the application folder, type the following to install the required gems:
+**2. Install dependencies**
 
-```
+```bash
+gem install bundler
 bundle install
 ```
 
 ## Making changes
 
-To make changes, edit the source files in the `source` folder.
-
-### Single page output
+Edit the source files in the `source` folder. Each section of the site is an `.html.md.erb` file.
 
-Although a single page of HTML is generated, the markdown is spread across
-multiple files to make it easier to manage. They can be found in
-`source/documentation`.
+### Adding content to an existing page
 
-A new markdown file isn't automatically included in the generated output. If we
-add a new markdown file at the location `source/documentation/agile/scrum.md`,
-the following snippet in `source/index.html.md.erb` includes it in the
-generated output.
+Content is split across multiple markdown files and manually included in `source/index.html.md.erb`. To add a new file (e.g. `source/documentation/agile/scrum.md`), add this line in the appropriate place in that file:
 
 ```
 <%= partial 'documentation/agile/scrum' %>
 ```
 
-Including files manually like this lets us specify the position they appear in
-the page.
-
-### Multiple pages
-
-To add a completely new page, create a file with a `.html.md` extension in the `/source` directory.
+### Adding a new page
 
-For example, `source/about.html.md` will be accessible on <http://localhost:4567/about.html>.
+Create a file with a `.html.md` extension anywhere in the `source` directory. For example, `source/about.html.md` will be served at <http://localhost:4567/about.html>.
 
 ## Preview
 
-Whilst writing documentation we can run a middleman server to preview how the
-published version will look in the browser. After saving a change, the preview in
-the browser will be refreshed automatically.
+Start a local server that auto-reloads when you save changes:
 
-The preview is only available on our own computer. Others won't be able to
-access it if they are given the link.
-
-Type the following to start the server:
-
-```
+```bash
 bundle exec middleman server
 ```
 
-If all goes well, something like the following output will be displayed:
-
-```
-== The Middleman is loading
-== LiveReload accepting connections from ws://192.168.0.8:35729
-== View your site at "http://Laptop.local:4567", "http://192.168.0.8:4567"
-== Inspect your site configuration at "http://Laptop.local:4567/__middleman", "http://192.168.0.8:4567/__middleman"
-```
-
-You should now be able to view a live preview at http://localhost:4567.
+Then open <http://localhost:4567> in your browser.
 
 ## Build
 
-If you want to publish the website without using a build script, you may need to
-build the static HTML files.
-
-Type the following to build the HTML:
+To generate static HTML files (e.g. to publish without a build script):
 
-```
+```bash
 bundle exec middleman build
 ```
 
-This will create a `build` subfolder in the application folder which contains
-the HTML and asset files ready to be published.
-
-[rvm]: https://www.ruby-lang.org/en/documentation/installation/#managers
-[bundler]: http://bundler.io/
+This creates a `build` folder containing the compiled HTML and assets.
 
 ## Publishing
 
-Run:
-```
+```bash
 bundle exec rake publish
 ```
+
+[rbenv]: https://github.com/rbenv/rbenv

source/cloud-native-platform/guides/federated-credentials.html.md.erb

@@ -47,7 +47,7 @@ Azure has a hard limit of **20 federated credentials per App Registration**. Eac
 Roles define what permissions the GitHub Actions workflow has. Common roles include:
 - `Reader` - Read-only access to resources
 - `Contributor` - Full management access
-- Custom roles - Organization-specific roles for fine-grained control
+- Custom roles - Organisation-specific roles for fine-grained control
 
 ### Scopes
 
@@ -140,7 +140,7 @@ Check the following before committing:
 1. **YAML Syntax** - Ensure proper indentation (2 spaces, not tabs)
 2. **Subject Count** - Count the lines under `subjects:` - must be ≤ 20
 3. **Scopes Format** - Verify subscription IDs and resource group names are correct
-4. **Role Names** - Ensure role names match available Azure roles in your organization
+4. **Role Names** - Ensure role names match available Azure roles in your organisation
 
 ### Step 5: Commit and Push
 
@@ -156,7 +156,7 @@ Navigate to the repository on GitHub and create a pull request. The infrastructu
 - Correct syntax and format
 - Appropriate permissions (following principle of least privilege)
 - Valid Azure scopes
-- Compliance with organizational policies
+- Compliance with organisational policies
 
 Once approved and merged, the terraform pipeline will automatically create your App Registration, service principal, federated credentials, and role assignments.
 

source/cloud-native-platform/new-component/github-repo.html.md.erb

@@ -16,7 +16,7 @@ Any developer added to [hmcts org](https://github.com/hmcts) is able to create a
     - [expressjs-template](https://github.com/hmcts/expressjs-template)
     - Alternatively you can simply create a blank directory. If so, we recommend you draw inspiration from an existing working repository.
 3. Repository should be public. [Gov UK guidance](https://www.gov.uk/service-manual/technology/making-source-code-open-and-reusable)
-4. Do not add any collaborators outside organization. All access needs to be managed with GitHub teams and not users.
+4. Do not add any collaborators outside the organisation. All access needs to be managed with GitHub teams and not users.
 
     _Note: You need to remove the user level admin access you got while creating the repository after you have added your team admins with the admin role._
 

source/cloud-native-platform/onboarding/team/github.html.md.erb

@@ -49,7 +49,7 @@ sscs: # product name in Jenkinsfile_CNP, this will be a 'short name' that your t
     contact_channel: "#sscs-tech" # public channel that you can be contacted at
     build_notices_channel: "#sscs-tech" # all build notices will be sent here
   tags:
-    application: "social-service-child-support" # name that your service is known to by FinOps, contact Bruce Rawstorne if unsure, you can put something in temporarily
+    application: "social-service-child-support" # name that your service is known to by FinOps. If unsure, verify in #finops channel. Temporary placeholders are allowed.
 ```
 
 Make sure your product name is not too long as some Azure resources have constraints on their length

source/cloud-native-platform/path-to-live/shutter.html.md.erb

@@ -11,7 +11,7 @@ weight: 5
 
 The purpose of this document is to describe the shutter solution design and its end to end implementation.
 
-## Implementation and Customization
+## Implementation and Customisation
 
 ### Solution
 
@@ -38,7 +38,7 @@ With everything setup to render a shutter page you can now swap the DNS from Azu
 1. Clone the [azure-public-dns](https://github.com/hmcts/azure-public-dns) repository
 2. Create a branch for your change
 3. Within the `environments` and `shuttering` folders check that a file exists for the environment and DNS zone you need to change e.g. `environments/prod/platform-hmcts-net.yaml`
-4. Lets assume this application need to be shuttered `www.decree-absolute.apply-divorce.service.gov.uk`
+4. Lets assume this application needs to be shuttered `www.decree-absolute.apply-divorce.service.gov.uk`
 5. Find the relevant file relating to the DNS zone `apply-divorce-service-gov-uk` (and the environment being shuttered) and make sure there is a [record](https://github.com/hmcts/azure-public-dns/blob/a24128ffdc47687937cbab37aaa46040786c7955/environments/prod/apply-divorce-service-gov-uk.yml#L41) for the service
 6. Now check that an equivalent shuttering [configuration](https://github.com/hmcts/azure-public-dns/blob/27f3b5df3a1d3b847f2ca196e77a41c9ab896cc1/shuttering/prod/apply-divorce-service-gov-uk.yml#L20) exists for this record
     - <details>