Technical Documentation Writing

This skill provides expert guidance for creating clear, comprehensive, and user-friendly technical documentation.

Documentation Types

1. Conceptual Documentation

Explains what and why - the ideas behind the software.

•System architecture overviews
•Design decisions and rationale
•Glossaries and terminology
•Background knowledge required to use the software

2. Procedural Documentation (Tutorials/How-tos)

Explains how - step-by-step instructions.

•Getting started guides
•Installation instructions
•Tutorials for specific tasks
•Troubleshooting guides

3. Reference Documentation

Provides lookup information - comprehensive technical details.

•API reference (functions, classes, methods)
•Configuration options
•CLI commands and flags
•Error codes and messages

4. Examples

Shows usage - practical code samples.

•Quick start examples
•Common use cases
•Integration patterns
•Complete working projects

Writing Principles

Clarity First

•Use simple, direct language
•One idea per sentence
•Short paragraphs (3-5 sentences max)
•Active voice over passive voice
•Present tense for descriptions

Avoid:

The configuration file is read by the system when initialization is performed.

Prefer:

The system reads the configuration file during initialization.

Audience Awareness

•Define your target audience explicitly
•State prerequisites upfront
•Don't assume knowledge without stating it
•Provide links to prerequisite materials

Consistency

•Use consistent terminology throughout
•Follow a style guide (Google, Microsoft, or custom)
•Consistent formatting for code, commands, paths
•Consistent structure across similar documents

Scannability

•Descriptive headings and subheadings
•Bullet points for lists
•Bold for key terms on first use
•Code blocks for commands and code
•Tables for structured data

Document Structure

Quickstart Guide

markdown

# Quickstart

Get up and running with [Project] in 5 minutes.

## Prerequisites
- Python 3.11 or higher
- pip package manager

## Installation

```bash
pip install project-name

Basic Usage

python

from project import main_function

result = main_function("input")
print(result)

Next Steps

code


### API Reference

For each function/class/method, document:

```markdown
## `function_name(param1, param2, *, keyword_only=None)`

Brief one-line description of what the function does.

Longer description if needed, explaining behavior, edge cases,
and important details.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `param1` | `str` | Description of param1 |
| `param2` | `int` | Description of param2 |
| `keyword_only` | `str \| None` | Optional. Description. Default: `None` |

### Returns

`ReturnType` - Description of return value.

### Raises

- `ValueError` - When param1 is empty
- `TypeError` - When param2 is not an integer

### Examples

```python
# Basic usage
result = function_name("hello", 42)

# With optional parameter
result = function_name("hello", 42, keyword_only="option")

Step 2: [Next Action]

Explanation...

python

code example

Note: Important information the reader should know.

Step 3: [Next Action]

...

Summary

You learned how to:

•✓ Accomplishment 1
•✓ Accomplishment 2
•✓ Accomplishment 3

Next Steps

•Next Tutorial - Continue learning
•Reference - Explore all options

code


### Concepts/Guide Structure

```markdown
# [Concept Name]

## Overview

One paragraph explaining what this concept is and why it matters.

## Background

Context needed to understand this concept. Link to external resources
if prerequisite knowledge is substantial.

## How It Works

Detailed explanation with diagrams if helpful.

┌─────────┐ ┌─────────┐ ┌─────────┐ │ Input │────▶│ Process │────▶│ Output │ └─────────┘ └─────────┘ └─────────┘

code


## Key Points

- **Point 1:** Explanation
- **Point 2:** Explanation
- **Point 3:** Explanation

## Common Patterns

### Pattern A
When to use and how...

### Pattern B
When to use and how...

## Pitfalls to Avoid

1. **Mistake name** - Why it's wrong and what to do instead
2. **Another mistake** - Explanation

## See Also

- [Related Concept](./other.md)
- [API Reference](./api.md#related)

Code Examples

Principles

•Complete and runnable - Reader can copy-paste and execute
•Minimal - Only include code relevant to the concept
•Realistic - Use realistic variable names and data
•Annotated - Comments explain the "why," not the "what"

Format

python

# Import required modules
from project import SequenceSet, distance

# Create sample data
sequences = [
    ["A", "B", "C", "A"],
    ["A", "C", "B", "A"],
    ["B", "A", "C", "B"],
]

# Create a SequenceSet from the raw data
seq_set = SequenceSet(sequences)

# Calculate pairwise distances using optimal matching
# The 'om' method uses edit distance with default costs
distances = distance(seq_set, method="om")

# Result is a symmetric distance matrix
print(distances)
# Output:
#        0    1    2
#   0  0.0  2.0  3.0
#   1  2.0  0.0  2.5
#   2  3.0  2.5  0.0

Progressive Complexity

Start simple, then build up:

python

# Basic usage - most common case
result = process(data)

# With options - customization
result = process(data, normalize=True, method="fast")

# Advanced - full control
result = process(
    data,
    normalize=True,
    method="fast",
    callbacks=[on_progress, on_complete],
    config=ProcessConfig(threads=4, cache=True),
)

Visual Elements

Diagrams

Use ASCII diagrams for simple concepts:

code

State Sequence:  A → A → B → B → B → C → A
                 ├─────┼───────────┼─────┤
                  Spell   Spell     Spells
                   (2)     (3)      (1)(1)

Use Mermaid for complex diagrams in supported renderers:

mermaid

graph LR
    A[Raw Data] --> B[Parse]
    B --> C{Valid?}
    C -->|Yes| D[Process]
    C -->|No| E[Error]
    D --> F[Output]

Tables

Use tables for comparisons and structured data:

Method	Speed	Memory	Use Case
`om`	Slow	High	Accurate sequence comparison
`hamming`	Fast	Low	Fixed-length sequences
`lcs`	Medium	Medium	Subsequence matching

Admonitions

Use callout boxes for important information:

Note: Additional context that's helpful but not critical.

Warning: Important information that could cause problems if ignored.

Tip: Helpful suggestion for better usage.

Example: Illustrative case showing real usage.

Documentation Tools

MkDocs Configuration

yaml

# mkdocs.yml
site_name: Project Documentation
site_description: Description for search engines
site_url: https://project.readthedocs.io

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - content.code.copy
    - content.tabs.link

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google

nav:
  - Home: index.md
  - Getting Started:
    - Installation: quickstart.md
    - First Steps: tutorials/first-steps.md
  - User Guide:
    - Concepts: concepts.md
    - Examples: examples.md
  - Reference:
    - API: api.md
    - CLI: cli.md
  - Development:
    - Contributing: contributing.md
    - Changelog: changelog.md

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed
  - toc:
      permalink: true

Docstring Style (Google)

python

def function(param1: str, param2: int) -> ReturnType:
    """Short description of function.

    Longer description explaining behavior, including edge cases
    and important details users should know.

    Args:
        param1: Description of first parameter.
        param2: Description of second parameter.

    Returns:
        Description of return value.

    Raises:
        ValueError: When param1 is empty.
        TypeError: When param2 is not an integer.

    Example:
        >>> result = function("hello", 42)
        >>> print(result)
        ReturnType(value="hello", count=42)

    Note:
        Additional information about usage or limitations.
    """

Review Checklist

Before publishing documentation:

• Accuracy: All code examples run without errors
• Completeness: All public APIs are documented
• Currency: Documentation matches current version
• Links: All internal and external links work
• Spelling/Grammar: No typos or grammatical errors
• Formatting: Consistent style throughout
• Accessibility: Images have alt text, good color contrast
• Navigation: Easy to find information, logical structure