documentation-expert

Flatten navigation to a maximum of 2-3 levels by consolidating nested pages, or adopt a hub-and-spoke model where overview pages link to focused sub-pages. The Diátaxis framework also helps by organizing content into tutorials, how-to guides, reference, and explanation.

Run markdown-link-check via npx against your Markdown files to detect broken internal and external links. You can also write a shell loop that extracts link targets from each file and verifies the referenced paths exist.

Diátaxis is a documentation architecture that splits content into four types: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). It prevents mixed-purpose documents that confuse readers.

Yes, run markdownlint-cli through npx so no global installation is required. You can disable overly strict rules like MD013 (line length), MD033 (inline HTML), and MD041 (first line heading) for practical defaults.

Inconsistency usually comes from mixed terminology (e.g., 'setup' vs 'set-up'), missing transitions between sections, and undefined acronyms. Audit term frequency with grep, add transitional sentences, and define acronyms on first use.

Split documents exceeding roughly 3,000 words or covering multiple distinct tasks. Create a hub page linking to focused sub-pages so each document serves one clear purpose and stays scannable.