Ezzi Clarity Portal

ESS-002 — Documentation Formatting Standard

Field Value
Document ID ESS-002
Title Documentation Formatting Standard
Status Approved baseline
Owners Arva Yusuf Ezzi and Vijay Panangipally
Effective Date 2026-08-23
Review Cycle Annual and upon material workflow change

This repository’s documents should read as professional business documents — clean, navigable, and free of clutter — while still rendering natively on GitHub with no build tooling. This standard defines both what to add and what to avoid.

Contents

1. Executive-summary openers

Every document in scope opens with one paragraph, immediately after the title (and any Document Control table), stating what the document is and why it exists — before anything else. A reader who only reads that paragraph should still know whether the document has what they need.

2. Tables of contents

A document of roughly 100 lines or more gets a table of contents: a ## Contents heading followed by a plain vertical list, one link per line — the standard convention for a table of contents in any formal document. Do not run the entries together into a single dot-separated paragraph (**Contents:** [A](#a) · [B](#b) · [C](#c)); despite being more compact, it reads as a run-on sentence of hyperlinks rather than a navigational element, which is a worse trade than the vertical list’s extra height.

Anchor text must match GitHub’s actual heading-slug algorithm: lowercase, spaces become hyphens, punctuation is stripped, and — this is the detail that breaks most tables of contents — em dashes are stripped entirely, not converted to a hyphen, so Article I — Purpose slugifies to article-i-purpose, with one hyphen, not two. Verify anchors resolve before publishing.

Shorter documents don’t need a table of contents at all — on a 40-line document it adds friction, not navigation.

3. What does not belong in the document body

This is the most important rule in this standard, and the one most often violated.

A document’s own git history, migration story, or drafting process does not belong in its body. “Adapted from X,” “carried forward as this repository became Y,” “this version includes one change from the original” — none of this is useful to a reader who wants to know what the policy is. That provenance belongs in governance/decision-log.md and governance/changelog.md, where it’s actually useful (a reader specifically looking for change history goes there on purpose), never narrated inline in a Constitution, a Security Policy, or a business plan.

The test: would this sentence appear in the equivalent document at a company that had always had one? A real corporation’s Constitution does not explain that it used to live in a different repository. If a sentence only makes sense in the context of this repository’s own editing history, cut it or move it to the changelog.

4. Section dividers

Do not place a horizontal rule (---) between every section. Section headings already provide the visual break; a rule after every single ## compounds into a document that feels chopped into fragments rather than one continuous piece of reasoning. Reserve horizontal rules for genuine part breaks in long, multi-part documents — most documents in this repository need none.

5. Document Control tables

Governance-tier documents use a plain two-column table — | Field | Value | — not bold field names inside a “Metadata” column. Keep it to the facts that matter (ID, status, owner, effective date, review cycle); it is front matter, not a place to restate the document’s own purpose in prose immediately below it.

6. GitHub Alert callouts

GitHub renders five callout types natively from blockquote syntax: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]. Use one where prose already contains a caveat, an unverified claim, a governed exception, or a risk — something a skimming reader could miss as a plain sentence. Reserve [!WARNING]/[!CAUTION] for things that are genuinely urgent or risky (the immigration-document exception in governance/security.md is the canonical example); routine caveats are [!NOTE]. A document that is all callouts has none — most of a document should be plain prose.

7. Mermaid diagrams

GitHub renders Mermaid diagrams natively from fenced ```mermaid blocks. Add one where a document describes a genuinely structural relationship — a hierarchy, a sequence, a flow. Do not add one merely to break up text: if a single sentence already conveys the relationship, a diagram is decoration, not clarity.

8. Purposeful emoji

A small, consistent set of emoji may be used as visual anchors — one per domain in a navigation table, one per row in a status table — where they genuinely help a reader scan a list faster. They are not a substitute for clear writing and should never appear mid-sentence or stacked for decoration. If removing an emoji would lose no information, it shouldn’t be there.

9. Collapsible reference sections

Use <details><summary>...</summary>...</details> for material a reader doesn’t need on a first pass but that should stay in the document — long tables, extended source excerpts, lengthy appendices. The <summary> line should describe what’s inside well enough to decide whether to expand it.

Relative Markdown links, section anchors for a specific point in a document, and link text that names the document or fact being referenced — never “here” or “this document.” Cross-references belong at natural points in the prose or in a closing “Related Documents” list, not stacked three deep inside a single sentence.

When a sentence would otherwise point to two or more distinct documents, break it into a short bulleted list — one link per line, with a trailing clause explaining what that specific link is for. This applies even to compact header metadata (a register’s **Related:** line): use a bulleted list under the label, not a comma-separated run of links on one line. The exception is when two links describe the same thing from two angles rather than pointing to separate resources — e.g. “kept in X, catalogued in Y” describing one record’s storage location and its register entry. Forcing that into a list fragments one coherent clause instead of clarifying it; leave it as prose. A short “(see A and B)” parenthetical is also fine as prose — the run-on problem is about long sentences carrying several links, not brief asides with two.

11. Scope

This standard applies to every living document in this repository outside archive/ — archived documents are frozen point-in-time snapshots, and reformatting them would misrepresent what they looked like when superseded.