Documentation Workflow Guide

Purpose

This workflow ensures that documentation, diagrams, and executable architecture models evolve together. By treating every inform ation artefact as code, teams maintain consistent narratives, review history, and traceability across the repository.

Branching and Reviews

  1. Create a feature branch for every documentation improvement. Align naming with the associated issue or change request.
  2. Edit Markdown, diagrams, and models together. Keep Structurizr, CALM, Mermaid, and narrative updates within the same chan ge set to avoid divergence.
  3. Preview locally. Render diagrams or generate the book preview to confirm formatting, spellings, and references.
  4. Open a pull request with a concise summary, detailed testing notes, and links to related issues.
  5. Request peer review. At least one reviewer validates technical accuracy, adherence to British English, and consistency wit h established terminology.

Automation and Checks

  • Continuous integration executes python3 generate_book.py && docs/build_book.sh to rebuild the book, regenerate diagrams, and surface linting feedback.
  • ADR validation runs python3 scripts/validate_adrs.py followed by python3 scripts/generate_adr_catalogue.py so that new decisions automatically populate the MkDocs navigation and change-log-friendly catalogue.
  • Link validation ensures Markdown references resolve correctly. Update links or add redirect stubs whenever file paths chan ge.
  • Diagram generation leverages Mermaid CLI during the build to refresh PNG artefacts. Never commit outdated diagram renders.
  • Spell checking and style checks enforce British English spellings and repository style conventions.

Merging and Maintenance

  • Merge only after all automated checks pass and reviewers approve.
  • Keep the workflow documented—update this file whenever the process evolves.
  • Periodically audit the documentation tree to remove dead links, regenerate diagrams, and validate that reference material remai ns accurate.

Incident Response

When link checkers or reviewers discover gaps:

  1. Reproduce the issue locally using the documented commands.
  2. Patch the affected artefacts (Markdown, diagrams, or models) within a dedicated branch.
  3. Extend tests or checks if the gap was not caught automatically.
  4. Document lessons learnt in the pull request or relevant chapter to prevent recurrence.

Publishing the Website

The website is published at https://aipurple.geon.se from the gh-pages branch of the repository.

  1. The workflow .github/workflows/build-mkdocs.yml builds the site with mkdocs build on every push or pull request that touches docs/ or mkdocs.yml.
  2. Only a push to main deploys: the workflow copies CNAME and .nojekyll into the build and force-pushes the result to gh-pages.
  3. In the repository settings, GitHub Pages is set to Deploy from a branch, branch gh-pages, folder / (root), with the custom domain aipurple.geon.se and Enforce HTTPS switched on once the certificate is issued.
  4. DNS holds a CNAME record for aipurple that points to the GitHub Pages host of the organisation (geonitab.github.io).