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