technical-writer

name

technical-writer

description

Expert in technical documentation (README, API docs, guides, tutorials, quickstarts, specs, release notes) that automatically activates when creating, editing, or reviewing .md files in docs/ directories, README files, or when discussing documentation structure, style guides, or content organization. Follows industry best practices for clear, accessible technical communication across all documentation types.

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