Documentation style guide¶
Authoring rules for MasteryHive platform documentation. Applies to public and staff pages unless a section says otherwise.
Voice¶
- Direct, precise, and evidence-based.
- Prefer present tense for current behaviour (“the service returns 422”).
- Prefer second person for integrator actions (“send
x-tenant-id”). - Do not market. Do not speculate. Mark unknowns as UNKNOWN.
Audience labelling¶
Use admonitions at the top of specialised pages:
| Label pattern | Use on |
|---|---|
| Audience · Partner | Integrator API and contracts |
| Audience · Public / Product | Product capability pages |
| Audience · Staff-only | Engineering, ops, troubleshoot, ADRs (never on the public allowlist) |
Public builds must not contain staff-only pages.
Terminology¶
| Prefer | Avoid |
|---|---|
| partner / integrator | customer engineer (ambiguous) |
| banking application / dashboard | “the backend” alone when the consumer matters |
session / session_id |
“job” for reconciliation windows |
tenant / x-tenant-id |
“org id” unless that is the field name |
| provisional | “temporary hack”, “docs-only stub” |
| UNKNOWN | “probably”, “seems like”, “I think” |
Product names: Fraud Detection, KYC / KYB, Banking Reconciliation, Case Management, AML and Regulatory Reporting.
Status words: only those in Status vocabulary.
Headings and capitalisation¶
- Title Case for page H1 only when it is a product or guide title; otherwise Sentence case is fine.
- H2/H3: Sentence case.
- Do not number headings unless the sequence is a required procedure.
- One H1 per page.
Status language¶
- Implementation status and product readiness use the approved vocabulary only.
- Do not invent parallel scales (
Code: Yes, “mostly done”, RAG colours without the rubric). - Provisional policy must say provisional / non-production, not “beta” unless an owner has named a beta programme.
Examples¶
- Prefer minimal, copy-pasteable JSON and curl.
- Redact secrets, tokens, and real tenant identifiers.
- State environment assumptions (local vs programme URL).
- Link OpenAPI or contracts instead of inventing fields.
Warnings and callouts¶
| Admonition | When |
|---|---|
!!! warning |
Contract traps, provisional policy, unsafe retries |
!!! danger |
Security / data-loss risk (staff pages mainly) |
!!! note |
Documentation status / last verified |
!!! info |
Audience or navigation tips |
Prohibited wording (published pages)¶
Do not publish:
- Process debris: “this pass”, “docs-only copy”, “found during review”, “bot”, scratch notes
- Raw programme ticket identifiers as narrative on public pages
- Temporary branch theatre: “uncommitted local changes”, “source tree dirty”, “N commits behind”
- Exploit-oriented security write-ups on public pages (finding identifiers, auth bypass detail, private deploy flags)
- Commit SHAs and repository paths on product pages — keep those in engineering evidence or page metadata on the staff site
Staff engineering pages may record repository evidence; still avoid bot commentary and ticket-shaped drafts.