Skip to content

Last Updated: 2026-05-03 Owner: Docs-Dev Summary: Process guide for updating, reviewing, and publishing documentation changes in the QuantMatrix docs system.

QuantMatrix Documentation Contributor Workflow

This document defines how we update and maintain the QuantMatrix documentation set.

Its goal is to make documentation changes easy, consistent, and reviewable.

1. Source of Truth

The source of truth for documentation is:

  • the Markdown files inside documentation/docs/

Generated outputs such as PDFs or hosted pages should be treated as derived artifacts.

2. Where Changes Should Go

Use these rules when adding or updating content:

  • architecture or design intent -> update the relevant design document
  • runtime or operational truth -> update runbooks, deployment docs, or alignment docs
  • delivery sequencing -> update roadmap, tracker, sprint plan, or execution board
  • API or schema change -> update the API reference or data dictionary
  • UI implementation drift -> update the UI alignment review and any affected operator docs

3. Required Steps For A Documentation Change

For any meaningful documentation update:

  1. Edit the relevant file in documentation/docs/
  2. Update the metadata fields at the top of the document if needed
  3. Update related docs if the change affects shared meaning
  4. Update master_index.md if a new document is added
  5. Regenerate documentation_catalog.md if document metadata or document inventory changed
  6. Refresh any generated documentation surface if needed
  7. Include a short note in the documentation changelog

Recommended top-of-file metadata fields: - Title - Tags - Last Updated - Owner - Summary

4. When To Update More Than One Document

A single implementation change often needs multiple doc updates.

Examples:

  • new API endpoint
  • API reference
  • data dictionary if new fields appear

  • runbook if operator workflow changes

  • UI workflow change

  • UI alignment review
  • operations runbook

  • go-live checklist if operator expectations change

  • new risk control

  • risk-related design docs
  • runbook
  • release checklist
  • incident playbook if response steps change

5. Review Checklist For Documentation Changes

Before a doc update is considered done, confirm:

  • the document still reflects the correct scope
  • naming is consistent across docs
  • current-state vs target-state language is clear
  • links still work
  • no critical operational or API detail was introduced in only one place

6. Suggested Ownership By Task Type

  • UI-Dev: screen, widget, navigation, and operator-flow docs
  • API-Dev: endpoint, request/response, and integration contract docs
  • Process-Dev: runtime service behavior, orchestration, and processing docs
  • QA-Dev: test-plan and validation evidence updates
  • Data-Dev: schema, Redis, persistence, and analytics-capture docs
  • Ops-Dev: deployment, runtime operations, monitoring, and release docs
  • Docs-Dev: cross-document consistency, master index, and changelog upkeep
  • Strategy-Dev: strategy logic, scanner, allocator, and trade-behavior docs
  • Risk-Dev: risk-control, halt, and safety-rule docs

7. Pull Request Expectations

For a documentation-heavy change, the PR should include:

  • what changed
  • why the change was needed
  • which docs were updated
  • whether the change reflects:
  • current implementation truth
  • target-state planning
  • both

Once the MkDocs site is stable, the next good step is:

  • automate documentation publishing with GitHub Pages
  • add lightweight docs review rules in pull requests