By name: writing-technical-documentation description: >- Guides writing clear, well-structured technical documentation following Mintlify's best practices (Diátaxis framework, audience awareness, style/tone, navigation, SEO/AEO). Use when writing, reviewing, or improving documentation, guides, tutorials, API references, or any user-facing technical content.
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.