Technical Documentation Expert

Overview

Provides expert guidance for creating clear, comprehensive, and user-friendly technical documentation following industry best practices and structured content models.

Core principle: Write for the audience with clarity, accessibility, and actionable content using standardized documentation patterns.

When to Use

Automatically activates when:

• Working with .md files in docs/ directories
• Creating or editing README files
• Editing documentation files or markup
• Discussing documentation structure, information architecture, or style guides
• Creating API documentation with examples and parameter tables
• Writing user guides, tutorials, or quickstarts
• Drafting release notes or change logs
• Structuring specifications or technical proposals

Manual invocation when:

• User explicitly asks about documentation best practices
• User needs guidance on content organization or structure
• User requests help with technical writing style
• User encounters documentation quality issues

When NOT to Use This Skill

Do not use this skill for:

• Creative writing or marketing copy
• Code implementation (documentation only)
• Project management documentation
• Internal team chat or informal notes
• Academic papers or research documentation

Core Expertise Areas

Content Types

1. Conceptual – Explains what something is and why it’s useful (“About…” articles)
2. Referential – Detailed reference information (API docs, syntax guides, parameter tables)
3. Procedural – Step-by-step task completion with numbered lists and gerund titles
4. Troubleshooting – Error resolution, known issues, and debugging guidance
5. Quickstart – Essential setup in 5 minutes/600 words maximum
6. Tutorial – End-to-end workflow with real-world examples and conversational tone
7. Release Notes – Version changes categorized by type (Features, Fixes, Breaking Changes)

Documentation Structure

Standard Article Elements:

• Titles: Sentence case, gerund for procedures, character limits by level
• Intros: 1-2 sentences explaining content
• Prerequisites and permissions when applicable
• Clear next steps

Information Architecture:

• Hierarchical structure with maximum 4 navigation levels
• Content ordering: Conceptual → Referential → Procedural → Troubleshooting

For detailed structure requirements: See ./references/style-guide.md section on Article Structure and Standard Elements.

Style Guide Principles

Apply formatting and style rules from the comprehensive style guide:

• Language: Clear, simple, active voice, sentence case
• Technical formatting: Code in backticks, UI in bold, placeholders in ALL-CAPS
• Structure: Numbered lists for procedures, bullets for non-sequential info
• Links: Descriptive text, no “click here”
• Alerts: Use Note, Tip, Important, Warning, Caution sparingly

For detailed formatting rules: See ./references/style-guide.md sections on Language and Tone, Technical Writing Conventions, and Structure and Format.

Procedural Content Ordering

Follow standard procedural sequence: Enabling → Using → Managing → Disabling → Destructive

Within individual steps: Optional info → Reason → Location → Action

For complete ordering guidelines: See ./references/style-guide.md section on Content Ordering Guidelines.

Development Workflow

1. Understand the Audience

• Identify user expertise level (beginner, intermediate, advanced)
• Determine user goals and tasks
• Consider context where documentation will be used
• Plan appropriate content depth and technical level

2. Choose Content Type

Select the appropriate content type:

• Need to explain a concept? → Conceptual
• Documenting API or syntax? → Referential
• How-to for specific task? → Procedural
• Debugging help? → Troubleshooting
• Quick setup needed? → Quickstart (≤5 minutes)
• End-to-end learning? → Tutorial
• Version changes? → Release Notes

3. Structure Content

Standard content sequence:

1. Title (sentence case, descriptive, within character limits)
2. Brief intro (1-2 sentences)
3. Prerequisites (if applicable)
4. Permissions statement (if required)
5. Main content (ordered appropriately by type)
6. Troubleshooting (embedded when helpful)
7. Next steps / Further reading

4. Apply Style Guide

Follow the comprehensive style guide for:

• Formatting code, UI elements, and placeholders
• Writing clear procedures with proper structure
• Adding accessibility features (alt text, sufficient contrast)
• Ensuring proper link formatting and context
• Using alerts appropriately

For complete style guide details, see: ./references/style-guide.md

5. Content Accuracy

Critical rule: Do not invent or assume information not present in source material.

• If gaps exist, ask user for missing information
• Do not create placeholder or speculative content
• Verify technical accuracy with authoritative sources
• Include working examples when possible

Problem-Solving Approach

1. Analysis Phase

• Review existing documentation structure and patterns
• Identify target audience and their needs
• Assess information architecture and navigation
• Check for consistency with project documentation standards

2. Solution Design

• Select appropriate content type for the task
• Plan information hierarchy and flow
• Consider accessibility and localization needs
• Design for different user expertise levels

3. Implementation

• Write clear, concise content following style guide
• Structure with appropriate headings and sections
• Include concrete examples where helpful
• Add tables for complex reference information
• Ensure proper formatting of code, UI, and placeholders

4. Validation

• Verify content accuracy and completeness
• Check that examples work as documented
• Ensure style guide compliance
• Validate accessibility (alt text, structure, contrast)
• Confirm navigation and links work correctly

Automated validation: Use ./scripts/validate_markdown.py <file> to check:

• Proper heading hierarchy (no skipped levels)
• Code block formatting (language tags, closing backticks)
• Link syntax and descriptive link text
• Basic document structure

Communication Style

Be Clear and Actionable:

• Use simple, direct language
• Provide specific examples and code snippets
• Break complex topics into digestible sections
• Include visual aids when they clarify concepts

Serve Multiple Expertise Levels:

• Layer content from simple to complex
• Provide quick reference sections
• Link to deeper explanations
• Use prerequisites to set expectations

Focus on User Goals:

• Organize by tasks users want to accomplish
• Use gerund titles for procedures (“Creating…”, “Configuring…”)
• Include “what you’ll learn” or “what you’ll build” statements
• Provide clear next steps after each article

Reference Materials

This skill references the comprehensive style guide for detailed guidance on all formatting rules.

See: ./references/style-guide.md for the complete technical writing style guide.

Quick Discovery: Search Patterns

For specific formatting rules in the large style guide, use grep to search:

• Alert formatting rules: Search for "alert" in ./references/style-guide.md
• Code block formatting: Search for "code" or "backticks" in ./references/style-guide.md
• Link formatting: Search for "link text" in ./references/style-guide.md
• Table formatting: Search for "table" in ./references/style-guide.md
• Heading hierarchy: Search for "heading" in ./references/style-guide.md
• Procedural step structure: Search for "step structure" or "Within Procedural" in ./references/style-guide.md
• Alt text requirements: Search for "alt text" in ./references/style-guide.md
• Placeholder conventions: Search for "placeholder" or "ALL-CAPS" in ./references/style-guide.md

Success Criteria

Documentation is successful when:

• Content is accessible to the target audience
• Structure follows the appropriate content type
• Examples clarify complex concepts
• Style guide rules are consistently applied
• Users can complete tasks using the documentation
• Information architecture supports easy navigation
• Content is accurate and up-to-date

Quick Reference: Common Patterns

README Structure

# Project Title (sentence case)

Brief description in 1-2 sentences.

## Prerequisites

- Item 1
- Item 2

## Installation

1. Step one
2. Step two

## Usage

Basic usage examples with code blocks.

## Documentation

Links to further reading.

API Documentation Pattern

## `functionName(param1, param2)`

Brief description of what the function does.

**Parameters:**

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| param1    | string | Description |
| param2    | number | Description |

**Returns:** Description of return value

**Example:**
\`\`\`language
// Working code example
\`\`\`

Release Notes Pattern

# Version X.Y.Z

## Features

- New feature description

## Fixes

- Bug fix description

## Breaking Changes

- Breaking change with migration path

## Improvements

- Enhancement description

Remember

• Always consider the audience first
• Choose the right content type for the task
• Follow style guide consistently
• Do not invent information – ask when unclear
• Include working examples
• Make content accessible
• Structure for easy navigation
• Validate before completion