Skip to content

Last Updated: 2026-05-03 Owner: Docs-Dev Summary: Writing and formatting standards for keeping QuantMatrix documentation clear, consistent, and maintainable.

QuantMatrix Documentation Style Guide

This guide defines the writing style for the QuantMatrix documentation set.

Its purpose is to keep the docs readable, consistent, and easy to search.

1. Writing Principles

Prefer writing that is: - direct - structured - explicit - easy to scan

Avoid: - vague wording - overloaded paragraphs - mixing target-state and current-state language without saying so

2. Document Structure

Each document should usually include:

  1. a short statement of purpose
  2. clear sections with headings
  3. lists or tables where structure helps
  4. a recommended next step when useful

Each maintained document should also include top metadata fields: - Title - Tags - Last Updated - Owner - Summary

3. Naming Rules

Use consistent names across documents.

Examples: - Momentum Radar - Active Strategy Watchlist - Risk & Health - Order Execution Service - Global Risk Manager

If the implementation differs from the target name, call that out explicitly instead of silently switching terms.

4. Current-State vs Target-State Language

Use these labels clearly:

  • Current implementation
  • Target state
  • Planned
  • Not yet implemented

This is especially important for: - UI documents - API docs - runbooks - roadmap documents

5. Lists and Tables

Use bullets for: - responsibilities - prerequisites - checklists

Use tables for: - columns - fields - ownership - milestone tracking - comparison summaries

6. Linking

Whenever useful, link related docs directly.

Examples: - architecture -> implementation spec - UI alignment review -> API reference - roadmap -> execution tracker - runbook -> incident playbook

7. Update Discipline

When adding a new document:

  • place it in the right section
  • add document metadata at the top
  • add it to master_index.md
  • add it to mkdocs.yml
  • add a short changelog note

8. Tone

The docs should feel: - calm - professional - practical - easy to hand to another engineer or operator

9. Preferred Outcome

A good QuantMatrix doc should let someone answer:

  • what this component does
  • what state it is in
  • how it interacts with the rest of the system
  • what still needs to be built