tomevault-io Writing technical documentation
Best practices for technical documentation, distilled from Mintlify's Guide to Technical Writing.
Content types (Diátaxis framework)
Categorize every page into exactly one type before writing:
| Type | Reader Goal | Structure | Assumed Knowledge |
|---|---|---|---|
| Tutorial | Learn through practice | Sequential steps, guided tasks | None (beginner) |
| How-to guide | Solve a specific problem | Problem-solution, logical sequence | Some (intermediate) |
| Reference | Look up precise details | Scannable facts, tables, specs | Significant (experienced) |
| Explanation | Understand concepts | Conceptual discussion, background | Any level |
Writing approach per type
Tutorials: Set expectations upfront on what the reader will achieve. Use incremental steps. Minimize choices. Point out milestones. Focus on actions over theory.
How-to guides: Write from the user's perspective, not the product's. Describe a logical sequence. Skip obvious steps ("Press enter to submit"). Minimize extraneous context.
Reference: Optimize for scannability. Prioritize consistency (tables, naming, specs). Avoid explanatory prose. Provide copy-paste-ready examples.
Explanation: Provide background context and design decisions. Acknowledge alternatives. Connect to other product areas or industry concepts.
Know your audience
Each piece of content should target one specific persona. Common personas:
- Technical decision maker evaluating architecture
- End user learning to get started or complete tasks
- Developer integrating the product
- AI agents/LLMs retrieving structured answers
Before writing, answer: What is the reader trying to accomplish? How much do they already know?
Writing for AI agents
Practices that help LLMs also help humans:
- Clear, descriptive headings
- Correct semantic markup
- Explicit prerequisites
- No vague references ("this", "it" without clear antecedent)
- Consistent terminology
- Defined acronyms and jargon
- Complete, runnable code examples
Style and tone
Core principles
- Be concise—readers want to achieve a goal, not read prose. Cut unnecessary words.
- Clarity over cleverness—simple, direct language. Avoid jargon and complex sentences.
- Active voice—"Create a configuration file" not "A configuration file should be created."
- Skimmable—use headings to orient. Break up text-heavy paragraphs.
- Second person—address the reader as "you."
Common mistakes to avoid
- Spelling and grammar errors (erode trust in the product)
- Inconsistent terminology ("API key" in one place, "API token" in another)
- Product-centric language the user wouldn't understand
- "Duh" documentation ("Click Save to save")
- Colloquialisms (hurt clarity, especially with localization)
Style guide references
When standardizing, lean on established guides:
Navigation and organization
Structural principles
- Descriptive headings: accurately describe what follows; avoid vague or clever labels.
- Self-contained pages: each page should be understandable independently (users and AI may land on any page).
- Semantic markup: use heading levels hierarchically; lists for lists, tables for tabular data, code blocks for code.
- Logical ordering: definitions before edge cases, common use case before advanced scenarios.
- Consistent terminology: one term per concept, everywhere.
Common pitfalls
- Overloaded categories (too many top-level sections)
- Buried essential content
- Unclear section names
- Outdated or deprecated content left without markers
Media
Use screenshots, GIFs, and videos sparingly and intentionally. Media is supplementary, not primary.
| Media | When to use | Maintenance cost |
|---|---|---|
| Screenshot | UI elements that are hard to describe in text | Low (~5 min to update) |
| GIF | Short, complex workflows or promotional content | Medium (~1 hour) |
| Video | Abstract concepts and long workflows | High (several hours) |
Always provide alt text for images, subtitles for videos, and transcripts for audio.
SEO and answer engine optimization
Content SEO
- Clear H1/H2/H3 structure with keywords in headings
- Short paragraphs and bullet points
- Descriptive internal links ("Learn more about rate limiting" not "Click here")
Technical SEO
- Meta titles (50-60 chars) and descriptions (150-160 chars) per page
- Descriptive alt text on images
- Mobile-friendly layout
- Up-to-date sitemap
AEO (for AI-powered search)
- Define terms explicitly on first use
- Provide complete, runnable code examples
- Make each section self-contained (AI retrieves sections independently)
- Document errors and edge cases with causes and solutions
- Mark deprecated features clearly
Maintenance
- Automate: track stale content, detect product changes, enforce standards with linters (e.g. Vale).
- Prioritize: focus review effort on high-traffic pages, not every page equally.
- Remove wrong docs: outdated/misleading content is worse than no content.
- Plan periodic resets: every 1-2 years, consider a structured audit and rewrite of the most impactful sections.
Content freshness
Optimize for evergreen content. If something represents a point-in-time snapshot, it's better as a blog post. Avoid embedding frequently-changing information (e.g. pricing) directly in docs.
Additional resources
For the full guide with expert quotes and detailed examples, see reference.md.
Source: rjdellecese/confect — distributed by TomeVault.