Conventions

The conventions below apply to every markdown file surfaced by Shannon — whether authored in this repo or federated from a source repo. Shannon’s CI enforces the frontmatter schema; the rest is honour-system but checked in PR review.

Language and tone

Australian English. organisation, optimisation, colour, centre, authorise, analyse.
Plain language. Short sentences. Active voice. No consultancy-speak.
Lead with the answer. The first paragraph of every page should answer “what is this and why do I care?”
No emojis in technical docs. House style.

Frontmatter schema

Every .md file must start with:

---
title: Human-readable title
system: salesforce | myob | xplan | hex | pwg-data | workato | azure | m365 | none
owner: firstname.lastname            # email local-part at pwg.com.au
status: current | draft | deprecated
last_reviewed: YYYY-MM-DD
tags: [integration, gl, etl]         # array of strings, lower-kebab
---

Rules:

system: none is the correct value for cross-cutting Shannon content (ADRs, glossary, policies, runbooks).
status: draft is appropriate for work-in-progress pages that are intentionally shipped incomplete.
status: deprecated pages are rendered with a banner and de-weighted in search.
last_reviewed older than 180 days triggers a stale-docs issue on the weekly CI cron.

The Zod schema in src/content/config.ts is authoritative. If this page and the schema disagree, the schema wins.

Five-file system contract

Every system documented under systems/<name>/ — federated from a source repo — should produce at minimum these five files:

File	Answers
`overview.md`	What is this system, who uses it, what business processes depend on it?
`architecture.md`	How is it structured? Mermaid diagrams of components and data flow.
`integrations.md`	What connects in and out? Named integration points, auth model, runbook links.
`admin-procedures.md`	How do you change it safely? Common admin tasks, change control, deployment path.
`known-issues.md`	Active quirks, workarounds, historical gotchas. Append-only unless genuinely resolved.

Additional files are welcome. These five are the floor.

Architecture Decision Records

See the ADRs index for MADR format specifics. Summary:

Sequentially numbered, four digits, zero-padded (0001, 0002, …).
One decision per ADR.
Append-only — supersede via a new ADR, don’t rewrite history.
Short. If it exceeds two printed pages, tighten it.

Diagrams

Mermaid, embedded in the markdown. Server-rendered to SVG by rehype-mermaid with strategy: 'img-svg' — the built site ships no client-side JS for diagrams.
No screenshots unless there is genuinely no alternative. Screenshots rot fast.

Recommended diagram type by use case:

Use case	Mermaid type
System / component topology	`flowchart LR`
Data flow between systems	`flowchart LR` with labelled edges
Sequence of calls across services	`sequenceDiagram`
State machine (e.g. client onboarding stages)	`stateDiagram-v2`
Entity relationships in a database	`erDiagram`
Release / dependency timeline	`gantt` (use sparingly)

Keep diagrams focussed. More than ~15 nodes on a single diagram is a signal to split.

File naming

kebab-case.md for all content files.
ADRs: NNNN-short-summary.md.
No spaces, underscores, or mixed case in filenames.

Where to put what

Content	Lives in
System-specific overview, architecture, integrations, admin procedures, known issues	That system’s source repo.
Cross-cutting ADRs, runbooks, policies, glossary, conventions	Shannon (this repo).
Live dashboards and status	Not Shannon. Hex, Azure Monitor, GitHub Projects — linked out from relevant Shannon pages.