Documentation standards - Jacob P Evans

The rules every page on this site follows. Author to these by default; when a rule and a page disagree, fix the page.

This page is the canonical standard for docs.jacobpevans.com. It exists so new pages land consistently no matter who — human or model — writes them.

Information architecture

The site is organized by domain, not by document type. The left sidebar has a small set of top-level dropdowns (Overview, Homelab infrastructure, Platform and tooling, AI and agents, Security and secrets, Reference). A reader picks a domain first, then narrows. Document type (the Diátaxis idea of tutorial, how-to, reference, explanation) is captured as page metadata — the page_type field below — not as navigation groups. Nesting docs under “How-to” / “Reference” headings suits a product with large workflows; this site is an ecosystem map for one reader, so domain-first navigation scans faster.

Page naming

Surface	Rule
Filename	Lowercase `kebab-case`. It is the URL slug — they never differ.
`overview.mdx`	Only for a group’s landing page.
Title	Sentence case: capitalize the first word and proper nouns only. Never a raw slug.
Ampersand	Use “and” in titles and labels. Keep `&` only inside an official product name.

Preserve these tokens exactly, wherever they appear in a title:

AI · API · AWS · BMC · CI/CD · DNS · GPU · HEC · IAM · IaC · IDS · IPS · K8s · LLM · LXC · macOS · MCP · MFA · MLX · MoE · Nix · OIDC · OTEL · OTLP · PR · README · SIEM · SOPS · TTL · UniFi · VLAN · VMID · VPN · YAML · ZFS

— plus proper nouns kept in their own casing:

Apple · Bifrost · Bitwarden · ChatGPT · Cribl · Docker · Doppler · GitHub · Keychain · Kubernetes · Mac · OpenBao · OpenTofu · OrbStack · Proxmox · Splunk

Renaming a file changes its slug. When you rename or move a page, add a redirects entry in docs.json (old → new) and update every inbound link so none rely on the redirect.

Frontmatter

Every content page starts with:

---
title: "Sentence case, acronyms preserved"
description: "One sentence: what the page helps you do or understand."
page_type: "reference" # one of: overview, how-to, explanation, reference, decision, repo
---

page_type records what the page is trying to do. Pick one:

`page_type`	Use for
`overview`	A group’s landing page: mental model and route map.
`explanation`	How something works and why — architecture, rationale.
`how-to`	Step-by-step setup or operation.
`reference`	Canonical tables, policies, naming rules, per-tool detail.
`decision`	”Why this way” — the tradeoff behind a choice.
`repo`	A single public repo explainer with source links and contracts.

Keep the sidebar scannable:

A dropdown shows at most ~3 group headers at once.
A group with more than ~6 pages splits into collapsible subgroups.
Nest at most two levels deep below a dropdown.

Writing style

Follow the Google developer documentation style guide: short sentences, one idea each, active voice, second person (“you”), sentence-case headings. Keep terms of art, but define each the first time you use it. The full voice-and-tone rules live in the repo’s AGENTS.md.

Sources

These standards derive from established documentation practice:

Source	What it informs
Diátaxis	The four document types, captured here as `page_type`.
Divio — The documentation system	The same four-type model, applied to structure.
Google developer documentation style guide	Sentence case, active voice, plain language.
Write the Docs — Documentation Guide	General authoring and maintenance practice.
Nielsen Norman Group — menu configurations	Navigation density and scannability.
Mintlify navigation	Dropdowns, groups, and how this site’s sidebar renders.

​Information architecture

​Page naming

​Frontmatter

​Navigation density

​Writing style

​Sources

Information architecture

Page naming

Frontmatter

Navigation density

Writing style

Sources