Create an end-to-end service guide or roadmap

These documents support planning, service context, integration points, and links to technical specifications so teams can move from discovery to delivery.

The information helps audiences understand how their software fits into the end-to-end service, and complements the API documentation by including links to API technical specifications.

Simple APIs might not need a separate service guide or roadmap. If the content is concise, it can be included in the API's own documentation.

Choose the right format

Each service guide and roadmap exists as a separate microservice owned by the API producer team.

Step 1: create a new microservice

1. Create a microservice repository in the Platform Catalogue with the type: service.
2. Give it a name that identifies it as a service guide or roadmap.
3. Do not select Make Private.
4. Set its Type to Empty.
5. Copy all files from the service guide skeleton into the repository.
6. Commit the changes, have your pull request approved by a teammate, and merge.

Step 2: create config files

1. Go to the Platform Catalogue to find and select your microservice.
2. Select Commissioning State under the Code section.
3. On the App Config Base row, select Add.
4. Fill out the Create App Config page, selecting the Base, QA, and Production environments.
5. Select Build to create config files.

Build and publish

Replace the placeholders and delete the angle brackets:

import uk.gov.platform.buildjobs.domain.variable.JavaType

new SbtMicroserviceJobBuilder(<YOUR-TEAM-NAME>, <NAME-OF-YOUR-REPO>, JavaType.OPENJDK_JRE21)
  .withTests("test")
  .withNodeJs(version = '22.2.0')
  .build(this as DslFactory)

Pipeline job:

new PipelineJobBuilder('<YOUR-TEAM-NAME>','<NAME-OF-YOUR-REPO-PIPELINE>')
  .buildMicroservice('NAME-OF-YOUR-REPO')
  .andThenDeployTo(QA)
  .build(this as DslFactory)

Step 4: create a frontend route

Your routes.yaml file must contain an entry for each service guide or roadmap. Example for a service guide:

<microservice-name>:
  environments:
    qa:
      - path: /guides/<path-of-your-service-guide>
    production:
      - path: /guides/<path-of-your-service-guide>

Example for a roadmap:

<microservice-name>:
  environments:
    qa:
      - path: /roadmaps/<path-of-your-roadmap>
    production:
      - path: /roadmaps/<path-of-your-roadmap>

Step 5: update the configuration files

Update the configuration files using this format:

{
  "identifier": "<name-of-microservice>",
  "name": "<human readable name for the documentation page>",
  "description": "<description of the service guide/roadmap>",
  "context": "<url-of-the-service-guide-or-roadmap>",
  "categories": ["<category-1>", "<category-2>"]
}

Deploy to production

Deploy your microservice to the Production environment as early as possible. Raise a support request for the API Platform team to review and approve your changes.

Design guidelines

• Audience: tailor content based on user types (individual, business, agent) with consistent terminology.
• Structure: break complex services into multiple pages; limit navigation depth to two levels.
• Diagrams: use flow diagrams to complement text; use swimlane diagrams to represent all actors. Ensure text stands alone for accessibility.
• Changelog: highlight significant updates — breaking changes, new endpoints, bug fixes. Omit minor typo fixes.
• Testing: test content with real users regularly. Keep content up to date with evolving user needs.