Skip to content

Documentation standards

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

These standards keep a site of more than a thousand pages consistent for human and agent authors. They replace the 2025 standards; the terminology section now lives in the glossary and the meta-model.

1. Say what is true, label it

Every page carries front matter doc_status and plane; the matching banner snippet follows the H1:

doc_status Banner Use
target --8<-- "includes/status/target.md" Design intent; nothing or only part exists in code
current includes/status/current.md What exists at recorded repository revisions
decision includes/status/decision.md ADRs and recorded choices (Proposed until accepted)
evidence includes/status/evidence.md Verified facts with evidence_date
historical includes/status/historical.md Kept for provenance; superseded; search: exclude: true
generated pages includes/status/generated.md Rendered from the model; never edited by hand

A target page always has a Current implementation section; "Nothing exists" is a valid body. Never describe a target as if it ran. Never use dates for plans; capability dependencies replace roadmaps.

Target to Current. A page changes doc_status from target to current only when a repository and revision are named in which the behaviour exists, the evidence is reproducible from that revision (build, test run, contract test or dated inspection), and the model entry's status changes in the same commit so the catalogs agree. Partly current pages say which parts exist. The Current state page is the site-wide inventory of what exists.

plane is one of the nine plane ids, pack:software-factory, pack:generated-saas, overview, cross-plane, decisions, reference, examples or stakeholders. Platform pages add platform: <slug>; service pages add service: <ServiceId>.

2. Facts live in the model, narrative in pages

  • model/**/*.yaml is the source of truth for planes, platforms, bounded contexts, services and all their facets, agents, skills, tools, profiles, workflows, templates, libraries, descriptors, gateways, stores, topologies, NFR classes, externals, components and traceability ids. Schemas are under model/schemas/; the generator validates on every mkdocs build and fails the build on model errors.
  • Generated pages carry the first-line marker GENERATED by tools/docs_model and generated: true in front matter. Edit the YAML, run python tools/docs_model generate (or mkdocs build), commit the regenerated files.
  • Hand pages include generated fragment sections with --8<-- "includes/generated/<kind>/<id>.md:<section>"; a fragment section always exists for every registry id, so an include never breaks.
  • Run python tools/docs_model nav after adding a platform or a service page; the nav blocks between # BEGIN/END GENERATED NAV markers are managed by the tool.
  • python tools/docs_model check reports stale generated files and nav; CI expects a clean check.

3. Service design page skeleton

python tools/docs_model scaffold service <ServiceId> writes the page once at <platform docs_dir>/services/<slug>/index.md. The H2 order is fixed:

Identity (fragment) · Purpose and responsibilities · Context and boundaries · Domain model · Entities and value objects · Data model and storage · APIs · Messages · Workers and jobs · Actors and grains · Sagas and long-running flows · Options and configuration · Metrics and observability · Security · Dependencies · Failure and recovery · NFR targets · Deployment · Current implementation · Later capabilities · Decisions and traceability · Related.

Rules: factual lists (fields, endpoints, events, workers, options, metrics, dependencies) come from fragments, never from hand tables; hand text explains purpose, boundaries, reasoning, examples (a JSON example of a request is welcome), what exists and what comes later. External-canonical and later services use the same skeleton with the integration contract or the trigger described.

4. Platform page set

Generated: bounded-contexts, microservices, apis, events, aggregate-roots, data-model, storage, workers. Hand: overview (purpose, role, C4 context fragment, responsibilities, integration, current implementation), workflows (sequence and state diagrams linked to events and commands), ui (Studio modules and BFF routes), security, observability, deployment, later-capabilities. Plane indexes include the six generated plane sections.

5. Agents, skills, tools, workflows

Agent specification pages include the generated role card after the status banner (includes/generated/agents/<id>.md:role-card) and keep the fixed hand sections: Purpose · Responsibilities · Inputs and outputs · Skills · Tools and side effects · Policies and memory · Collaboration · Evaluation · Lifecycle · Current implementation · Related. Vendor model names never appear in a specification; profiles do. MassTransit, Azure Service Bus and Qdrant are profiles, never mandates (ADR-0012, ADR-0013). Bicep does not exist in the estate (ADR-0004).

6. Diagrams

  • Mermaid only, inline. Use flowchart for structure, sequenceDiagram for interactions, stateDiagram-v2 for lifecycles, erDiagram for data, C4Context/C4Container/C4Component/C4Deployment for C4 views, mindmap for maps. No external images.
  • No spaces in node ids; quote labels with punctuation. In sequence diagrams, message text must not contain ;, +, - after the colon, or parentheses pairs: they are Mermaid tokens.
  • No explicit colors or styles; the site theme styles diagrams (D38).
  • Generated pages cap at six diagrams; large ER diagrams split per aggregate.
  • Relative Markdown links only; mkdocs build --strict fails on a broken link or anchor.
  • Canonical anchors are generated once (svc-, bc-, evt-, agg-, tbl-, pf-, pl-, agent-, tool-, prof-, tpl-, lib-, dsl-, gw-, store-, fr-/fux-/nfr-/xl- prefixes). Hand pages must not define ids with those prefixes.
  • Canonical ConnectSoft.Documentation pages are linked, never copied. Cross-repository relative links are not allowed.

8. Language and tone

English. Short sentences. State facts and decisions; cite the decision id (D-nn) or ADR when a page depends on one. No marketing in design pages; stakeholder pages live under stakeholders/. No HTML in Markdown except the generator's anchor spans.

9. Review checklist

  1. Front matter complete; banner matches doc_status.
  2. No hand-written table duplicates a generated fragment.
  3. Every statement about what exists is backed by the verification record or a repository revision.
  4. Diagrams render (no Mermaid console errors in a browser check).
  5. python tools/docs_model check clean; mkdocs build --strict green. The documentation pipeline runs the same three commands as a gate before the shared build template (azure-pipelines-documentation.yml), after installing requirements-docs.txt.
  6. Decisions referenced exist in the decision log or the ADR index.
  7. New open questions are added to the decision log, not left in prose.