Principles, frameworks, and workflows for writing docs that humans read AND AI agents consume. Not the feature reference — the thinking behind it.
The rest of the NookDocs docs describe how features work. This section describes why you'd author content a particular way and what patterns tend to win. Think of it as the opinion that backs the tools.
The LLM-first bet
Every guide here is written under one assumption: docs are read by humans AND by AI agents, and those two audiences share most of the page but disagree on edges. Humans want UI cues and reassurance; agents want component spec links and canonical URLs. NookDocs ships the Visibility component so you can target both from one MDX source — but that's the mechanism. The guides here cover the editorial strategy.
Writing
Writing for LLMs
Our unique angle. How LLMs actually read docs — skim patterns, chunk boundaries, token economics, citation mechanics — and how to author pages that degrade well under agent consumption.
GEO — AI search optimization
Generative Engine Optimization. ChatGPT, Perplexity, Gemini, Google AI Overviews. What ranks in the answer box. Why it's different from classic SEO. Seven GEO patterns that work.
Style and tone
Second person, active voice, heading intent, the technical-writing fundamentals that still rank in 2026. The Microsoft / Google style guides distilled to one page.
Content types
The Diátaxis framework — tutorials vs how-to guides vs reference vs explanation. Why most docs fail by mixing types, and how to split when you catch yourself mixing.
Understand your audience
Three human personas (evaluators / implementers / operators) plus the fourth, LLM agents. How to find out who actually reads your docs, what they're trying to do, and how to ship content that matches.
Publishing
SEO for docs
On-page SEO playbook for technical documentation — title + meta + headings + links + sitemap + schema.org. The reliable foundation, sibling to the GEO guide.
Accessibility
WCAG 2.2 AA patterns specific to docs — keyboard nav, screen readers, colour contrast, alt text, focus management. Cheap on day one, expensive to retrofit.
Media
Screenshots, diagrams, videos, embeds — what to capture, how to annotate, how to size, how to write alt text that serves both humans and LLMs.
Linking
Internal clusters build authority. Descriptive anchor text. Orphan audits. External link hygiene. The linking playbook.
Navigation IA
Information architecture principles behind the sidebar — group granularity, tab vs group choice, nested subgroups, drill-down vs expand-all. The thinking behind the config reference.
Maintaining
Improving docs
Metrics-driven iteration. Five specific signals (zero-result searches, bounce rate, support ticket URLs, thumbs-down comments, time-to-first-success), a weekly review rhythm, quarterly audits, what NOT to measure.
Maintenance
Keeping docs fresh as the product ships. What rots + how fast, five staleness signals, quarterly freshness audit, screenshot discipline, deprecation process, retirement decision tree.
VS Code fork. .cursor/rules/ template + tab-complete + Cmd+K + Composer patterns for NookDocs MDX.
Windsurf
Cascade-driven multi-file editor. .windsurf/rules/ template. GUI-first, good for non-dev writers.
Use cases
Larger playbooks for specific docs-site shapes.
Developer documentation
End-to-end recipe for API + SDK + CLI docs. The seven sections every dev docs site needs, page budget per section, day-1 + first-quarter + second-quarter work plans.
Help center
Support-style docs for end-users. Voice tuning for non-technical readers, FAQ patterns, troubleshooting trees, ticket-deflection loops.
Knowledge base
Internal-only docs for your own team. Runbooks, ADRs, postmortems, onboarding flows. Separate tenant vs unified tenant architectures.
Internationalization
Multi-language docs without burning the translation budget. Priority order, RTL considerations, professional vs hybrid vs machine translation, honest cost breakdown.
Headless + custom frontend
When to render docs outside the default shell — in-product panels, mobile apps, marketing sites. API surface, SSR vs client-only, migration-back patterns.
Advanced
Niche guides for teams that have outgrown the defaults.
Git concepts for writers
Minimum viable Git for non-dev writers. Commits, branches, PRs, merge conflicts — no terminal jargon, just the mental model.
Branches for docs workflows
When to branch vs commit-to-main, naming conventions, reviewer patterns, merge strategies, PR template. Lighter discipline than engineering branching.
Configure automerge
Safe auto-merge setup for docs PRs. GitHub's auto-merge + required CI + CODEOWNERS. Reduce review friction on low-risk changes.
Migrating from custom MDX
You already use MDX — Next.js, Astro, Docusaurus, Contentlayer, hand-rolled. The path to NookDocs without losing content, URLs, or tooling you like.
Custom page layouts
mode: center / wide / custom for per-page layout variation. Narrow narratives, wide reference tables, custom-mode landing pages. Lighter touch than headless.
Roadmap
Additional per-source migration guides (Docusaurus, GitBook, ReadMe, MkDocs) + team-scaling playbooks (growing a docs team from one writer to five, organisational governance at 1000+ pages) ship in subsequent waves.
How to use this section
Skim the titles
Each guide declares a specific angle. If the title doesn't match a question you've asked recently, skip.
Read start-to-finish
These aren't reference docs — pages are narrative. Jumping to the middle loses the framing.
Link back, not forward
Every guide ends with cross-links to the feature pages it justifies. Use the guides as the "why" and the feature pages as the "how."
Contributing a guide
See something missing? Open an issue at github.com/Codivion/NookDocs/issues with a title + outline. The best guides come from real experience — if you've written docs for 5+ years, we want your opinion.
Related
Human vs agent content — the canonical reference for the dual-audience model these guides assume
