Doc Style Guide

Voice, headings, code blocks, when to use which template. The discipline that makes the docs feel like one product.

This is the reference every other template in meta/ defers to. Runbooks, ADRs, postmortems, pattern entries, weekly logs, blog posts — they all share this voice and these conventions. The shared shape is what makes ~250 weekly logs, 30 phase docs, dozens of runbooks, and a hundred-plus pattern entries read as a single coherent body of work over 60 months.

The discipline isn’t aesthetic. It’s a forcing function: short sentences and tight paragraphs make sloppy thinking visible; time-stamped tools make unfalsifiable claims impossible; single-source-of-truth links make documentation drift surface as broken cross-references. Style is how the ROOT practice resists rotting at scale.

If you’re picking a template and wondering “do I follow the template’s conventions or this guide’s conventions when they seem to differ?” — they shouldn’t. If they do, this guide wins, and the template needs a fix.

Cut every marketing word in the final pass

The fastest review pass on any doc: search for “robust,” “leverage,” “seamless,” “scalable,” “best-in-class,” “powerful,” “we believe,” “it is recommended.” Each hit is either deletable or replaceable with something specific. The doc gets shorter and sharper. This is the same discipline the AI Learning Protocol calls “push back on shallow conclusions” — applied to your own prose.

---

Voice

Second person, active voice, opinionated, no filler.

• Yes: “Read the WAL chapter; you’ll need it for Phase 3.”
• No: “It is recommended that the reader explores the WAL chapter as preparation for the upcoming Phase 3.”

Don’t hedge. If the right answer is Iceberg over Delta for ROOT’s homelab, say it. Cite the trade-off. Move on.

Short sentences. Tight paragraphs. If a paragraph is more than 4 sentences, it’s probably two paragraphs.

No emojis unless the user explicitly asks for them.

---

Headings

H1 (#)         — page title (matches frontmatter title)
H2 (##)        — major sections
H3 (###)       — sub-sections
H4 (####)      — rare; usually a sign you should split into a sub-section

Title-case for H1 + H2; sentence-case for H3 + H4.

Use colons in headings when you need to subordinate one phrase to another (“Section: details”) — never em-dashes. Em-dashes belong in prose, not in heading hierarchies.

---

Frontmatter

Every page starts with YAML frontmatter:

---
title: "Pattern title shown in nav"
description: "1-2 sentence summary used by search and social cards."
slug: short-kebab-case
tags: [year-1, foundations, os]
status: STUB | OUTLINE | DEEP    # patterns only
year: 1                          # program docs only
phase: 1                         # phase docs only
---

Slugs match filenames (the file phase-1.md has slug: phase-1).

The description: field is mandatory on any doc that ships to the public site — it’s what shows up in search and social previews, and a missing one is the kind of bug nobody notices until it’s been wrong for a year.

---

Code blocks

Use language hints:

kubectl get pods

func main() { ... }

apiVersion: v1
kind: Pod

For terminal output mixed with commands, use bash and prefix commands with $:

$ kubectl get pods
NAME           READY   STATUS
postgres-0     1/1     Running

For directory trees, use plain text:

basecamp/
├── applications/
└── charts/

---

When to use which template

What you’re writing	Template
Recurring operational procedure (3am-readable)	runbook-template.md
Real-time during an active incident	incident-template.md
After an incident: blameless 5-whys + action items	postmortem-template.md
Architectural decision with trade-offs + alternatives	adr-template.md
Sunday weekly journal	weekly-log-template.md
Pattern library entry (STUB/OUTLINE/DEEP)	pattern-template.md
Blog post for abukix.dev/blog	blog-template.md

---

Internal links

Use relative paths from the current file:

See [Phase 1](../program/year-1/phase-1.md).
See the [control-loops](../patterns/foundations/control-loops.md) pattern.

Don’t use absolute URLs for internal docs (they break when the rendering layer changes — Astro vs MkDocs vs anything else).

---

When to use callouts

Use > blockquotes for the page’s elevator pitch (the 1-sentence summary at top). Use them sparingly elsewhere — not as decoration.

> This page summarizes how the X pattern works in basecamp.

Starlight asides (:::tip, :::note, :::caution) are reserved for non-obvious insights — the kind of thing future-you would highlight on a re-read. They are not for emphasis on routine claims; if every paragraph has a callout, none of them stand out.

Asides earn their place by being skip-or-die

A :::caution block must be a thing the reader can’t afford to miss. A :::tip must reward the reader who reads it. If you can delete the aside without losing the doc’s load-bearing claim, delete it — the page reads tighter and the remaining asides become signal instead of decoration.

---

”Time-stamp tools, not patterns”

Patterns don’t age. Tools age. When mentioning a specific tool or version, anchor to a date:

• Yes: “As of 2025-10, Cilium is the canonical K8s CNI for eBPF observability.”
• No: “Cilium is the canonical K8s CNI.”

Patterns get no timestamp. Tools always do. This is the same rule the AI Learning Protocol enforces on AI assistants — apply it to your own writing.

---

”Single source of truth”

If information already lives in a pattern entry, phase doc, or runbook, link to it — don’t repeat it. Duplication ages badly and creates drift. When you find yourself re-explaining something for the third time, the doc that should explain it is missing or weak — fix that doc instead of leaning harder on copy-paste.

---

Anti-patterns

Anti-pattern	Why
Long paragraphs of unbroken prose	Future-you skims; structure = headings + lists
Emojis sprinkled for “warmth”	Dilutes signal; stay disciplined
Marketing-style hedging (“we believe”, “leverage”, “robust”)	Engineering writing; cut every marketing word
Tutorial-shape phase docs	Phase docs are FRAMES; you do the investigation
Tools without time-stamps	Will age badly
Em-dashes in headings	Use colons; em-dashes are for prose
Missing description: frontmatter on a public doc	Breaks search and social cards silently

---

Cross-reference

• Program context: Master Plan, AI Learning Protocol, ops-handbook plan
• Every template in this directory defers to this guide for voice and convention questions.