Technical Writer

Expert technical writing skill with automated documentation tools for modern software projects. Provides comprehensive documentation quality analysis, README generation, CHANGELOG maintenance, and API documentation formatting to ensure professional, consistent, and up-to-date project documentation.

Overview

This skill delivers production-ready technical writing capabilities through four Python automation tools and extensive reference documentation. Whether auditing documentation quality, generating README files, maintaining changelogs, or formatting API documentation, this skill ensures your project documentation meets professional standards and stays current with your codebase.

Target Users:

• Engineering teams maintaining project documentation
• Open source maintainers managing README and CHANGELOG files
• Technical writers standardizing documentation across projects
• DevOps teams automating documentation in CI/CD pipelines
• Product teams ensuring user-facing docs are complete

Quantified Benefits:

• 50% time savings on documentation tasks through automation
• 30% improvement in documentation consistency and quality
• 90% reduction in documentation drift and outdated content
• 60% faster onboarding for new team members with better docs

Use this skill when:

• Auditing documentation quality across a project
• Generating or updating README files with current project state
• Maintaining CHANGELOG files synchronized with git commits
• Formatting API documentation for consistency
• Preparing documentation for releases
• Standardizing documentation across multiple repositories

Core Capabilities

• Documentation Quality Analysis - Comprehensive quality scoring with readability metrics, completeness checks, broken link detection, and actionable recommendations
• Automated README Generation - Template-based README creation with automatic project discovery, dependency detection, and example generation
• CHANGELOG Management - Git-synchronized changelog maintenance with conventional commit parsing, semantic versioning support, and Keep a Changelog formatting
• API Documentation Formatting - Consistent API doc formatting with OpenAPI/Swagger support, endpoint documentation, and code example generation
• Documentation Standards Enforcement - Style guide validation, terminology consistency, and format standardization across projects
• Integration with /update.docs - Seamless integration with repository documentation workflows

Quick Start

Analyze Documentation Quality

# Basic documentation audit
python scripts/doc_quality_analyzer.py ./docs

# Detailed quality report with JSON output
python scripts/doc_quality_analyzer.py ./docs --format json --verbose

# Check specific documentation types
python scripts/doc_quality_analyzer.py ./docs --types readme,api,guides

Generate or Update README

# Generate comprehensive README
python scripts/readme_generator.py . --template comprehensive

# Update existing README with project changes
python scripts/readme_generator.py . --update --preserve-custom

# Generate minimal README for new project
python scripts/readme_generator.py . --template minimal

Maintain CHANGELOG

# Sync CHANGELOG with recent git commits
python scripts/changelog_generator.py --since HEAD~10 --prepend

# Generate CHANGELOG from last tag
python scripts/changelog_generator.py --format keep-a-changelog

# Generate CHANGELOG for specific version
python scripts/changelog_generator.py --version 2.0.0 --output CHANGELOG.md

Format API Documentation

# Format API documentation from OpenAPI spec
python scripts/api_doc_formatter.py openapi.yaml --output docs/api.md

# Generate API docs from code annotations
python scripts/api_doc_formatter.py src/ --scan-annotations

# Validate API documentation consistency
python scripts/api_doc_formatter.py docs/api.md --validate

Access Documentation

• Technical Writing Standards: references/technical_writing_standards.md
• API Documentation Patterns: references/api_documentation_patterns.md
• Developer Documentation Guide: references/developer_documentation_guide.md

Key Workflows

Workflow 1: Documentation Quality Audit (30-45 min)

Scenario: Regular documentation health check or pre-release audit

# 1. Run comprehensive quality analysis
python scripts/doc_quality_analyzer.py . --verbose

# Output shows:
# - Overall quality score (0-100)
# - Readability metrics (grade level, complexity)
# - Completeness assessment (missing sections, examples)
# - Link validation (broken links, redirects)
# - Style consistency (voice, terminology, formatting)
# - Actionable recommendations

# 2. Review quality report
# Identify critical issues (broken links, missing content)
# Prioritize improvements (high-impact fixes first)

# 3. Fix identified issues
# Update documentation based on recommendations
# Add missing sections, examples, or links

# 4. Re-run analysis to verify improvements
python scripts/doc_quality_analyzer.py . --format json > quality-report.json

# 5. Generate summary for team
# Share quality score and improvement metrics
# Reference: references/technical_writing_standards.md

Time Estimate: 30-45 minutes (vs 1-2 hours manual audit)

Success Criteria:

• Quality score ≥ 80/100
• Zero broken links
• Readability grade level appropriate for audience
• All required sections present
• Terminology consistent across docs

Workflow 2: README Creation/Update (1-2 hours)

Scenario: New project setup or major version update requiring README changes

# 1. Generate comprehensive README from template
python scripts/readme_generator.py . --template comprehensive

# Tool automatically:
# - Discovers project structure and tech stack
# - Extracts dependencies from package files
# - Generates installation instructions
# - Creates usage examples from code
# - Adds badges and shields
# - Formats sections consistently

# 2. Review generated README
# Check accuracy of auto-discovered information
# Verify examples are clear and working
# Ensure all sections are relevant

# 3. Customize as needed
# Add project-specific content
# Include unique setup requirements
# Add architecture diagrams or screenshots
# Reference: references/developer_documentation_guide.md

# 4. Update with project changes (for existing projects)
python scripts/readme_generator.py . --update --preserve-custom

# Tool updates:
# - Dependency versions
# - Installation steps
# - API references
# - Maintains custom sections unchanged

# 5. Validate README quality
python scripts/doc_quality_analyzer.py README.md

# 6. Commit changes
git add README.md
git commit -m "docs(readme): update with current project state"

Time Estimate: 1-2 hours (vs 3-4 hours manual creation)

Success Criteria:

• All standard sections present (overview, installation, usage, etc.)
• Installation instructions tested and accurate
• Code examples working and current
• Links validated and functional
• Consistent formatting throughout

Workflow 3: CHANGELOG Maintenance (15-30 min)

Scenario: Regular changelog updates or preparing for a release

# 1. Sync CHANGELOG with recent git commits
python scripts/changelog_manager.py --sync-git --since v1.5.0

# Tool automatically:
# - Parses conventional commits (feat, fix, docs, etc.)
# - Groups commits by type
# - Generates Keep a Changelog format
# - Adds links to commits/PRs
# - Preserves manual entries

# 2. Review generated entries
# Verify commit categorization
# Check for missing context
# Ensure user-facing language

# 3. Enhance entries with context
# Add breaking change notices
# Include migration guides
# Reference related issues
# Reference: references/technical_writing_standards.md

# 4. Prepare for release
python scripts/changelog_manager.py --prepare-release v2.0.0

# Tool:
# - Creates release section
# - Moves Unreleased items to release
# - Updates version references
# - Adds release date

# 5. Validate CHANGELOG format
python scripts/doc_quality_analyzer.py CHANGELOG.md --types changelog

# 6. Commit changes
git add CHANGELOG.md
git commit -m "docs(changelog): prepare for v2.0.0 release"

Time Estimate: 15-30 minutes (vs 45-60 minutes manual maintenance)

Success Criteria:

• All commits since last release documented
• Entries grouped by type (feat, fix, breaking, etc.)
• Keep a Changelog format followed
• Breaking changes clearly marked
• Links to commits/PRs included

Workflow 4: Pre-Release Documentation Review (1-2 hours)

Scenario: Comprehensive documentation check before major release

# 1. Run full documentation audit
python scripts/doc_quality_analyzer.py . --format json --verbose > pre-release-audit.json

# Review critical items:
# - Broken links (must fix)
# - Missing sections (must add)
# - Outdated examples (must update)

# 2. Update README for new release
python scripts/readme_generator.py . --update --preserve-custom

# Verify:
# - Installation instructions current
# - Examples use latest API
# - Version numbers updated
# - Breaking changes documented

# 3. Finalize CHANGELOG
python scripts/changelog_manager.py --prepare-release v2.0.0

# Ensure:
# - All changes since last release included
# - Breaking changes highlighted
# - Migration guide present (if needed)

# 4. Update API documentation
python scripts/api_doc_formatter.py docs/api/ --validate --update

# Verify:
# - All endpoints documented
# - Request/response examples current
# - Authentication documented
# - Error codes explained

# 5. Run final quality check
python scripts/doc_quality_analyzer.py .

# Criteria:
# - Quality score ≥ 85/100
# - Zero broken links
# - All critical sections complete
# - Readability appropriate

# 6. Generate documentation report
echo "## Pre-Release Documentation Review" > docs-review.md
echo "" >> docs-review.md
python scripts/doc_quality_analyzer.py . >> docs-review.md

# 7. Commit all documentation updates
git add docs/ README.md CHANGELOG.md docs-review.md
git commit -m "docs(release): update all documentation for v2.0.0"

Time Estimate: 1-2 hours (vs 3-5 hours manual review)

Success Criteria:

• All documentation updated for release
• Quality score ≥ 85/100
• Zero broken links or errors
• Breaking changes clearly documented
• Migration guides complete
• API documentation current

Workflow 5: API Documentation Creation (2-4 hours)

Scenario: Creating comprehensive API documentation for a new service or major API version

# 1. Generate API docs from OpenAPI specification
python scripts/api_doc_formatter.py specs/openapi.yaml --output docs/api-reference.md

# Tool generates:
# - Endpoint documentation (path, method, description)
# - Request/response schemas
# - Authentication requirements
# - Example requests and responses
# - Error code documentation

# 2. Enhance with code annotations (if no OpenAPI spec)
python scripts/api_doc_formatter.py src/api/ --scan-annotations --output docs/api-reference.md

# Tool scans:
# - Endpoint decorators/annotations
# - Function docstrings
# - Type hints
# - Validation rules

# 3. Validate API documentation
python scripts/api_doc_formatter.py docs/api-reference.md --validate

# Checks:
# - All endpoints documented
# - Request/response examples present
# - Authentication documented
# - Error handling explained
# - Consistent formatting

# 4. Add integration examples
# Manually add real-world usage examples
# Include authentication flows
# Show common request patterns
# Document error handling
# Reference: references/api_documentation_patterns.md

# 5. Format for consistency
python scripts/api_doc_formatter.py docs/api-reference.md --format --update

# Ensures:
# - Consistent section structure
# - Standard code block formatting
# - Proper HTTP status codes
# - Uniform terminology

# 6. Generate supplementary docs
# Create getting started guide
# Add authentication setup
# Include rate limiting info
# Document versioning strategy

# 7. Run quality check
python scripts/doc_quality_analyzer.py docs/api-reference.md --types api

# 8. Commit documentation
git add docs/api-reference.md
git commit -m "docs(api): create comprehensive API documentation"

Time Estimate: 2-4 hours (vs 6-10 hours manual creation)

Success Criteria:

• All API endpoints documented
• Request/response examples for each endpoint
• Authentication clearly explained
• Error handling documented
• Code examples working and tested
• Consistent formatting throughout
• Quality score ≥ 80/100

Workflow 6: Technical Diagram Generation (30-60 min)

Scenario: Creating architecture, process flow, or data model diagrams for documentation

# 1. Architecture diagram for system documentation
python scripts/mermaid_diagram_generator.py --type architecture \
    --input system-design.json --output markdown \
    --title "Microservices Architecture"

# Tool generates:
# - Component diagram with layered structure
# - Connection flows between services
# - External system integrations
# - Color-coded component types

# 2. Sequence diagram for API interaction documentation
python scripts/mermaid_diagram_generator.py --type sequence \
    --input auth-flow.json --output markdown

# Tool generates:
# - Participant definitions with roles
# - Message flows with labels
# - Synchronous/async calls
# - Activation indicators

# 3. Class diagram from source code (auto-discovery)
python scripts/mermaid_diagram_generator.py --type class \
    --scan src/models/ --output markdown \
    --title "Domain Model"

# Tool scans and generates:
# - Class definitions with attributes
# - Method signatures
# - Inheritance relationships
# - Associations between classes

# 4. ERD for database documentation
python scripts/mermaid_diagram_generator.py --type erd \
    --input schema.json --output markdown

# 5. State diagram for workflow documentation
python scripts/mermaid_diagram_generator.py --type state \
    --input order-lifecycle.json --output markdown

# 6. Embed in documentation
# Copy generated Mermaid blocks into documentation
# Verify rendering in GitHub/GitLab/docs site

Time Estimate: 30-60 minutes (vs 2-3 hours manual diagram creation)

Success Criteria:

• Diagrams accurately represent system/data/process
• Mermaid syntax valid and renders correctly
• Consistent styling across diagrams
• Diagrams embedded in documentation
• All relationships clearly shown

Workflow 7: Business Process Documentation (1-2 hours)

Scenario: Creating process diagrams for business analysts or stakeholder presentations

# 1. Swimlane diagram for cross-functional process
python scripts/mermaid_diagram_generator.py --type swimlane \
    --input order-fulfillment.json --output markdown \
    --title "Order Fulfillment Process"

# Tool generates:
# - Department/role lanes
# - Process steps within lanes
# - Cross-lane handoffs
# - Color-coded lanes

# 2. Customer journey map
python scripts/mermaid_diagram_generator.py --type journey \
    --input onboarding-journey.json --output markdown

# Tool generates:
# - Journey sections/phases
# - Touchpoints with satisfaction scores
# - Actor annotations
# - Experience visualization

# 3. Project timeline (Gantt chart)
python scripts/mermaid_diagram_generator.py --type gantt \
    --input project-plan.json --output markdown

# Tool generates:
# - Phased task sections
# - Dependencies between tasks
# - Milestones
# - Critical path highlighting

# 4. Prioritization matrix (Quadrant chart)
python scripts/mermaid_diagram_generator.py --type quadrant \
    --input features.json --output markdown \
    --title "Feature Prioritization"

# Tool generates:
# - Labeled axes (effort/value, risk/impact)
# - Quadrant labels
# - Positioned feature points
# - Visual prioritization

# 5. Mindmap for brainstorming documentation
python scripts/mermaid_diagram_generator.py --type mindmap \
    --input improvement-ideas.json --output markdown

# 6. Timeline for roadmap communication
python scripts/mermaid_diagram_generator.py --type timeline \
    --input roadmap-2025.json --output markdown

Time Estimate: 1-2 hours (vs 3-4 hours manual creation)

Success Criteria:

• Diagrams clear and readable for business audience
• Cross-functional flows accurately represented
• Handoffs and dependencies visible
• Consistent visual style
• Embedded in stakeholder documentation

Workflow 8: Interactive Documentation Creation (10-30 min)

Scenario: Using guided wizards to create documentation through step-by-step interactive workflows

# 1. Start interactive README wizard
python scripts/interactive_doc_wizard.py --workflow readme

# Wizard guides through 8 steps:
# Step 1: Project name and description
# Step 2: Technology stack detection (auto-detected)
# Step 3: Installation instructions
# Step 4: Usage examples
# Step 5: API overview (if applicable)
# Step 6: Contributing guidelines
# Step 7: License selection
# Step 8: Preview and confirmation

# 2. Run CHANGELOG workflow for release preparation
python scripts/interactive_doc_wizard.py --workflow changelog

# Wizard guides through 6 steps:
# - Version number and release type
# - Commit range selection
# - Change categorization review
# - Breaking changes documentation
# - Release notes enhancement
# - Output format selection

# 3. Documentation audit workflow
python scripts/interactive_doc_wizard.py --workflow audit --output audit-report.md

# Wizard guides through 7 steps:
# - Select documentation scope (README, API, guides)
# - Configure quality thresholds
# - Run automated analysis
# - Review findings by severity
# - Generate improvement recommendations
# - Create action items
# - Export audit report

# 4. API documentation workflow
python scripts/interactive_doc_wizard.py --workflow api-docs

# Wizard guides through 10 steps:
# - Source selection (OpenAPI, code annotations, manual)
# - Endpoint discovery
# - Authentication documentation
# - Request/response examples
# - Error handling documentation
# - Rate limiting configuration
# - Output format selection

# 5. User guide workflow
python scripts/interactive_doc_wizard.py --workflow user-guide

# Wizard guides through 12 steps:
# - Target audience definition
# - Guide structure selection
# - Getting started content
# - Feature documentation
# - Troubleshooting section
# - FAQ generation
# - Review and finalization

# 6. Non-interactive mode with config file
python scripts/interactive_doc_wizard.py --config readme_config.yaml --output README.md

# 7. Dry-run mode (preview without writing)
python scripts/interactive_doc_wizard.py --workflow readme --dry-run

Available Workflows:

Workflow	Steps	Time	Description
readme	8	10-15 min	Interactive README creation with project analysis
api-docs	10	15-20 min	Generate API reference from code or specs
changelog	6	5-10 min	Create changelog from git history
audit	7	10-15 min	Quality assessment of existing documentation
user-guide	12	20-30 min	Interactive user guide generation

Time Estimate: 10-30 minutes per workflow (vs 1-3 hours manual creation)

Success Criteria:

• All wizard steps complete successfully
• Generated documentation passes quality analyzer (score >= 80)
• Output matches project context and requirements
• Config file mode available for automation
• Dry-run mode works for preview

Python Tools

1. Documentation Quality Analyzer

Comprehensive documentation quality assessment with actionable insights.

Key Features:

• Overall quality scoring (0-100 scale)
• Readability metrics (grade level, complexity, sentence length)
• Completeness assessment (missing sections, examples, links)
• Link validation (broken links, redirects, external availability)
• Style consistency checks (voice, terminology, formatting)
• Multi-format output (text, JSON, HTML report)
• Comparative analysis (track quality over time)

Common Usage:

# Basic quality analysis
python scripts/doc_quality_analyzer.py ./docs

# Detailed JSON report
python scripts/doc_quality_analyzer.py ./docs --format json --output quality-report.json

# Check specific documentation types
python scripts/doc_quality_analyzer.py ./docs --types readme,api,guides --verbose

# Compare with baseline
python scripts/doc_quality_analyzer.py ./docs --baseline quality-baseline.json

Use Cases:

• Pre-release documentation audits
• Regular documentation health checks
• CI/CD quality gates for documentation
• Tracking documentation improvements over time
• Identifying documentation debt
• Onboarding documentation reviews

Output Example:

Documentation Quality Report
============================

Overall Score: 85/100 (Good)

Metrics:
- Readability: 88/100 (Grade level: 9.2)
- Completeness: 82/100 (3 sections missing examples)
- Link Health: 90/100 (2 broken links found)
- Style Consistency: 85/100 (4 terminology inconsistencies)

Critical Issues:
1. Broken link in installation.md (line 45)
2. Missing API examples in api-reference.md
3. Inconsistent terminology: "user" vs "account"

Recommendations:
1. Fix broken links (high priority)
2. Add code examples to API documentation
3. Standardize terminology using style guide
4. Improve readability of advanced-topics.md

2. README Generator

Automated README creation and updates with template support.

Key Features:

• Multiple template options (minimal, standard, comprehensive)
• Automatic project discovery (tech stack, dependencies, structure)
• Dependency extraction (package.json, requirements.txt, etc.)
• Installation instruction generation
• Code example generation from source
• Badge and shield generation
• Section customization and preservation
• Update mode (preserves custom content)

Common Usage:

# Generate comprehensive README
python scripts/readme_generator.py . --template comprehensive

# Update existing README
python scripts/readme_generator.py . --update --preserve-custom

# Minimal README for quick start
python scripts/readme_generator.py . --template minimal --no-badges

# Custom sections
python scripts/readme_generator.py . --sections "overview,install,usage,api"

Use Cases:

• New project initialization
• Major version updates
• Open source project setup
• Standardizing README across organization
• Automated documentation in CI/CD
• README refresh for archived projects

Output Example:

# Project Name

Brief description auto-generated from package.json or project metadata

## Overview
[Auto-generated from project structure and code]

## Installation
```bash
npm install project-name
# or
pip install project-name

Quick Start

[Auto-generated examples from code]

API Reference

[Links to detailed API documentation]

Contributing

[Standard contributing guidelines]

License

MIT

### 3. CHANGELOG Manager

Git-synchronized changelog maintenance with conventional commit parsing.

**Key Features:**
- Git commit synchronization (automatic changelog from commits)
- Conventional commit parsing (feat, fix, docs, breaking, etc.)
- Keep a Changelog format support
- Semantic versioning integration
- Release preparation automation
- Manual entry addition
- Grouping and categorization
- Link generation (commits, PRs, issues)
- Breaking change highlighting

**Common Usage:**
```bash
# Sync with recent git commits
python scripts/changelog_manager.py --sync-git

# Sync since specific version
python scripts/changelog_manager.py --sync-git --since v1.5.0

# Add manual entry
python scripts/changelog_manager.py --add "feat" "Added new API endpoint for user management"

# Prepare for release
python scripts/changelog_manager.py --prepare-release v2.0.0

# Validate CHANGELOG format
python scripts/changelog_manager.py --validate

Use Cases:

• Regular changelog maintenance
• Release preparation
• Post-merge documentation
• Automated changelog in CI/CD
• Conventional commit enforcement
• Historical documentation

Output Example:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [Unreleased]

### Added
- New API endpoint for user management (#123)
- Support for OAuth2 authentication (#125)

### Changed
- Updated dependency versions for security (#124)

### Fixed
- Fixed race condition in cache invalidation (#126)

## [2.0.0] - 2025-11-28

### Breaking Changes
- Removed deprecated v1 API endpoints
- Changed authentication scheme to OAuth2

### Added
- Comprehensive API documentation
- New user management features

[Unreleased]: https://github.com/user/repo/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/user/repo/releases/tag/v2.0.0

4. API Documentation Formatter

Consistent API documentation formatting with OpenAPI support.

Key Features:

• OpenAPI/Swagger specification parsing
• Code annotation scanning (decorators, docstrings, type hints)
• Endpoint documentation generation
• Request/response schema formatting
• Authentication documentation
• Error code documentation
• Example generation (requests and responses)
• Format validation and consistency checking
• Multi-format output (Markdown, HTML, JSON)

Common Usage:

# Generate from OpenAPI spec
python scripts/api_doc_formatter.py specs/openapi.yaml --output docs/api.md

# Scan code annotations
python scripts/api_doc_formatter.py src/api/ --scan-annotations

# Validate existing API docs
python scripts/api_doc_formatter.py docs/api.md --validate

# Format for consistency
python scripts/api_doc_formatter.py docs/api.md --format --update

Use Cases:

• API documentation creation
• OpenAPI to Markdown conversion
• API documentation validation
• Format standardization across APIs
• Automated doc generation in CI/CD
• API versioning documentation

Output Example:

## GET /api/users/{id}

Retrieve a user by ID.

### Authentication
Required: Bearer token

### Parameters

| Name | Type | Location | Required | Description |
|------|------|----------|----------|-------------|
| id | string | path | yes | User ID |

### Response

**Status:** 200 OK

```json
{
  "id": "user-123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-11-28T10:00:00Z"
}

Errors

Status	Code	Description
404	USER_NOT_FOUND	User with specified ID does not exist
401	UNAUTHORIZED	Invalid or missing authentication token

### 5. Mermaid Diagram Generator

Comprehensive diagram generation for technical and business documentation.

**Key Features:**
- Technical diagrams: flowcharts, sequence, class, ERD, state, architecture
- Business analysis diagrams: swimlanes, journey maps, Gantt charts, quadrants, timelines, mindmaps
- Multiple input formats (JSON, YAML)
- Multiple output formats (Mermaid, Markdown, HTML)
- Code scanning for class diagram generation
- Complementary to business-analyst stakeholder diagrams

**Common Usage:**
```bash
# Generate flowchart from JSON definition
python scripts/mermaid_diagram_generator.py --type flowchart --input process.json

# Generate sequence diagram for API flows
python scripts/mermaid_diagram_generator.py --type sequence --input api-flow.yaml

# Generate class diagram by scanning source code
python scripts/mermaid_diagram_generator.py --type class --scan src/models/

# Generate swimlane for cross-functional processes (BA use case)
python scripts/mermaid_diagram_generator.py --type swimlane --input order-fulfillment.json

# Generate customer journey map (BA use case)
python scripts/mermaid_diagram_generator.py --type journey --input onboarding.json

# Generate Gantt chart for project timeline
python scripts/mermaid_diagram_generator.py --type gantt --input project.json

# Generate priority quadrant matrix
python scripts/mermaid_diagram_generator.py --type quadrant --input features.json

# Output as Markdown with title
python scripts/mermaid_diagram_generator.py --type architecture --input system.json \
    --output markdown --title "System Architecture"

Diagram Types:

Type	Category	Description
flowchart	Technical	Process flows, decision trees, workflows
sequence	Technical	API calls, service interactions, message flows
class	Technical	Object models, inheritance hierarchies
erd	Technical	Database schemas, entity relationships
state	Technical	State machines, workflow states, lifecycles
architecture	Technical	System architecture, component diagrams
swimlane	Business	Cross-functional process flows with role/dept lanes
journey	Business	Customer/user journey maps with touchpoints
gantt	Business	Project timelines, milestones, dependencies
quadrant	Business	Priority matrices, effort/impact analysis
timeline	Business	Event timelines, roadmaps, milestones
mindmap	Business	Brainstorming, idea organization

Use Cases:

• Architecture documentation for technical specs
• API interaction documentation (sequence diagrams)
• Database schema documentation (ERDs)
• Process documentation for business analysts
• Cross-functional workflow documentation (swimlanes)
• Customer experience mapping (journey maps)
• Project planning visualization (Gantt)
• Feature prioritization (quadrant charts)
• Roadmap communication (timelines)

Output Example (Swimlane):

%% Order Fulfillment Process
%% Swimlane Process Diagram
flowchart LR
    subgraph customer[Customer]
        order(["Place Order"])
        receive(["Receive Package"])
    end

    subgraph sales[Sales Team]
        verify["Verify Order"]
        confirm["Send Confirmation"]
    end

    subgraph warehouse[Warehouse]
        pick["Pick Items"]
        pack["Pack Order"]
        ship["Ship"]
    end

    order --> verify
    verify --> confirm
    confirm --> pick
    pick --> pack
    pack --> ship
    ship -.->|Tracking info| receive

    style customer fill:#e3f2fd,stroke:#666
    style sales fill:#fff3e0,stroke:#666
    style warehouse fill:#e8f5e9,stroke:#666

Complementary Design:

• business-analyst-toolkit/stakeholder_mapper.py: Stakeholder relationship diagrams (people/orgs)
• technical-writer/mermaid_diagram_generator.py: All other diagram types (technical + business)

6. Interactive Documentation Wizard

Step-by-step guided documentation creation through interactive CLI workflows.

Key Features:

• 5 interactive workflows (readme, api-docs, changelog, audit, user-guide)
• Project auto-detection (language, framework, tests, CI)
• Decision tree navigation (adaptive questions based on context)
• Multiple output formats (markdown, html, json)
• Config file mode for non-interactive/automated usage
• Dry-run mode for preview without writing
• Integration with existing tools (doc_quality_analyzer, readme_generator, changelog_generator)

Common Usage:

# Start README wizard interactively
python scripts/interactive_doc_wizard.py --workflow readme

# Run audit workflow with output file
python scripts/interactive_doc_wizard.py --workflow audit --output audit_report.md

# Non-interactive mode with config file
python scripts/interactive_doc_wizard.py --config readme_config.yaml --output README.md

# Dry-run mode (preview without writing)
python scripts/interactive_doc_wizard.py --workflow readme --dry-run

# Show available workflows
python scripts/interactive_doc_wizard.py --help

Available Workflows:

Workflow	Steps	Time Est.	Description
readme	8	10-15 min	Interactive README creation with project analysis
api-docs	10	15-20 min	Generate API reference from code or specs
changelog	6	5-10 min	Create changelog from git history
audit	7	10-15 min	Quality assessment of existing documentation
user-guide	12	20-30 min	Interactive user guide generation

Use Cases:

• First-time README creation for new projects
• Release preparation with changelog and migration docs
• Documentation quality audits before releases
• API documentation from scratch or OpenAPI specs
• User guide creation for developer onboarding
• Automated documentation generation in CI/CD pipelines
• Standardized documentation across multiple repositories

Output Example:

============================================================
          INTERACTIVE DOCUMENTATION WIZARD
============================================================
Version: 1.0.0

Available Workflows:
  1. README Creation (8 steps, ~10-15 min)
  2. API Documentation (10 steps, ~15-20 min)
  3. Changelog Generation (6 steps, ~5-10 min)
  4. Documentation Audit (7 steps, ~10-15 min)
  5. User Guide Creation (12 steps, ~20-30 min)

Select a workflow (1-5): 1

============================================================
README CREATION WORKFLOW
============================================================

Step 1/8: Project Information
------------------------------------------------------------
Auto-detected project name: my-awesome-project
Is this correct? (Y/n): y

Step 2/8: Technology Stack
------------------------------------------------------------
Detected languages: Python (78%), JavaScript (22%)
Detected framework: FastAPI
Detected package manager: pip
Include detected stack? (Y/n): y

[... continues through all steps ...]

Step 8/8: Preview & Confirm
------------------------------------------------------------
Preview generated README.md:

# my-awesome-project
...

Write to README.md? (Y/n): y
✓ README.md created successfully!

Reference Documentation

Detailed guides available in the references/ directory:

Documentation Standards

technical_writing_standards.md - Comprehensive documentation standards including:

• Documentation hierarchy and organization
• Required sections for each doc type (README, API, guides, tutorials)
• Versioning and changelog standards
• Link management and validation
• Code example standards (format, testing, maintenance)
• Screenshot and diagram guidelines
• Accessibility requirements
• Multi-language documentation strategy
• Documentation review process
• Quality metrics and KPIs

Writing Style Guide

developer_documentation_guide.md - Writing conventions covering:

• Voice and tone (active voice, conversational, professional)
• Terminology and word choice
• Sentence and paragraph structure
• Technical writing patterns
• Grammar and punctuation rules
• Formatting conventions (headings, lists, code blocks)
• Common writing mistakes to avoid
• Localization considerations
• Readability optimization
• Style consistency enforcement

API Documentation Best Practices

api_documentation_patterns.md - API-specific guidance including:

• API documentation structure and organization
• Endpoint documentation templates
• Request/response documentation
• Authentication and authorization documentation
• Error handling and status codes
• Rate limiting and pagination
• Versioning strategy documentation
• Code example best practices (multiple languages, error handling)
• Interactive documentation (Swagger UI, Postman collections)
• API changelog maintenance
• Getting started guides
• API deprecation communication

Best Practices Summary

Documentation Quality Standards

Readability:

• Target appropriate grade level for audience (typically 8-10)
• Use short sentences (< 20 words average)
• Break up long paragraphs (< 5 sentences)
• Use active voice
• Define technical terms

Completeness:

• Include all required sections
• Provide working code examples
• Document error cases
• Include troubleshooting sections
• Add success criteria

Maintainability:

• Keep documentation close to code
• Automate where possible
• Use version control
• Regular audits and updates
• Clear ownership

Consistency:

• Follow style guide
• Use standard terminology
• Consistent formatting
• Uniform voice and tone
• Template-based generation

Common Documentation Pitfalls

Avoid:

• Outdated examples or screenshots
• Broken links or references
• Assuming prior knowledge
• Vague or ambiguous instructions
• Missing error handling
• Inconsistent terminology
• Poor readability (too technical or too simple)
• No maintenance plan

Instead:

• Automate documentation updates
• Validate links regularly
• Write for beginners
• Provide clear, step-by-step instructions
• Document all error cases
• Use terminology consistently
• Match readability to audience
• Schedule regular documentation reviews

Documentation Review Checklist

Before Publishing:

• Quality score ≥ 80/100
• All links validated and working
• Code examples tested
• Screenshots current and accurate
• Style guide followed
• Grammar and spelling checked
• Readability appropriate for audience
• All required sections present
• Version numbers current
• Breaking changes documented

Integration

Integration with /update.docs Command

This skill powers the /update.docs slash command for automated documentation maintenance:

# The /update.docs command uses these tools:
# 1. readme_generator.py --update (updates README statistics)
# 2. changelog_manager.py --sync-git (syncs CHANGELOG with commits)
# 3. doc_quality_analyzer.py (validates documentation quality)

# Manual usage:
/update.docs

# The command automatically:
# - Scans agents/ and skills/ directories
# - Updates counts in README.md and CLAUDE.md
# - Adds recent commits to CHANGELOG.md
# - Regenerates catalog files
# - Validates all changes

Integration with Code Review Workflow

Works seamlessly with code-reviewer skill:

# 1. Code review identifies documentation issues
python skills/engineering-team/code-reviewer/scripts/pr_analyzer.py 123

# 2. Analyze documentation quality
python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py docs/

# 3. Update documentation based on findings
python skills/engineering-team/technical-writer/scripts/readme_generator.py . --update

# 4. Validate improvements
python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py docs/

CI/CD Integration

Add documentation quality gates to your pipeline:

# .github/workflows/documentation.yml
name: Documentation Quality

on: [pull_request]

jobs:
  docs-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.8'

      - name: Analyze Documentation Quality
        run: |
          python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py . --format json > quality.json
          SCORE=$(jq '.overall_score' quality.json)
          if [ "$SCORE" -lt 80 ]; then
            echo "Documentation quality score ($SCORE) below threshold (80)"
            exit 1
          fi

      - name: Validate Links
        run: |
          python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py . --check-links

      - name: Check CHANGELOG Updated
        run: |
          python skills/engineering-team/technical-writer/scripts/changelog_manager.py --validate

Pre-commit Hooks

Enforce documentation standards locally:

# .git/hooks/pre-commit
#!/bin/bash

# Check if README or docs modified
if git diff --cached --name-only | grep -E '(README.md|docs/)'; then
  echo "Validating documentation..."

  # Run quality check
  python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py . || exit 1

  # Validate links
  python skills/engineering-team/technical-writer/scripts/doc_quality_analyzer.py . --check-links || exit 1

  echo "Documentation validation passed"
fi

Additional Resources

• Documentation Standards: references/technical_writing_standards.md
• Writing Style Guide: references/developer_documentation_guide.md
• API Best Practices: references/api_documentation_patterns.md
• Python Tools: scripts/ directory
• /update.docs Command: commands/workflow/update.docs.md

Getting Help

1. Quality issues: Review technical_writing_standards.md for quality criteria
2. Writing guidance: Consult developer_documentation_guide.md for style conventions
3. API documentation: See api_documentation_patterns.md
4. Tool usage: Run any script with --help flag for detailed options
5. Integration: See /update.docs command documentation for workflow automation

---

Version: 1.1.0 Last Updated: 2025-12-16 Documentation Structure: Progressive disclosure with references/ Integration: Powers /update.docs command and CI/CD documentation workflows