Documentation Offboarding

Use this guidance when a documentation source, content area, or documentation site is being retired or removed from the Developer Portal.

When to offboard

Typical triggers:

1. Product/service is decommissioned.
2. Documentation source repository is no longer maintained.
3. Content is replaced by a new canonical source.
4. Team ownership has ended and no successor owner is assigned.

Offboarding outcomes

1. Users are not left with broken links.
2. Replacement content is clearly signposted where available.
3. Portal navigation and search do not surface stale pages.
4. Ownership and support references are removed or updated.

Offboarding flow

flowchart TB
    A[Identify offboarding need] --> B[Confirm owner and approval]
    B --> C[Decide replacement or retirement path]
    C --> D[Plan deprecation notice and migration links]
    D --> E[Update navigation and references]
    E --> F[Remove or archive source content]
    F --> G[Run validation and publish]
    G --> H[Monitor for broken links and user feedback]

Checklist: offboarding a content area

1. Confirm accountable owner for the offboarding change.
2. Identify impacted pages and inbound links.
3. Publish a clear deprecation notice with timeline.
4. Link users to replacement content (if any).
5. Update all indexes/navigation pages.
6. Remove stale page links from related docs.
7. Run local and CI validation checks.
8. Verify published portal pages and search results.

Checklist: offboarding a full documentation site from portal ingestion

1. Confirm business/product decision and owner approval.
2. Edit sources.json in ministryofjustice/ministry-of-justice-developer-portal and remove the source entry or set enabled to false.
3. Remove site references from contributor/onboarding docs.
4. Remove generated links from index and navigation pages.
5. Ensure redirects or migration notes exist for high-traffic pages.
6. Verify no broken local links remain after build.
7. Raise a pull request in ministryofjustice/ministry-of-justice-developer-portal with the offboarding changes.
8. Request review by posting the PR in #ask-developer-experience and include impact notes. 9.

Validation checks

1. Build the documentation output using the repository’s standard build workflow.
2. Verify navigation links in the generated output.
3. Run built-site link checking before publishing.

This page was last reviewed on 9 July 2026. It needs to be reviewed again on 9 January 2027 by the page owner #developer-experience-alerts .