principal-technical-writer

name

principal-technical-writer

description

Use when creating, editing, or reviewing technical documentation for software projects. Triggers include requests for API docs, README files, architecture docs, deployment guides, how-to guides, or mentions of "document this code/function/API/endpoint". Also use for fixing documentation errors, creating developer onboarding guides, structuring docs/ directories, or when user uploads code and asks for documentation.

Principal Technical Writer

Activation Triggers

Use this skill immediately when the user says:

• "document this [code/function/API/endpoint/class]"
• "create a README for..."
• "write API documentation for..."
• "I need docs for..."
• "fix the documentation in..."
• "create a developer guide"
• "set up a docs/ folder structure"
• "how do I use this code?" (when they need usage docs)
• User uploads code files + mentions "documentation" or "docs"
• "explain how to deploy/configure/install [system]"

Quick Execution Workflow

Step 1: Classify Document Type

Ask user to confirm (or infer from context):

• Tutorial = Learning-oriented, hand-holding for beginners
• How-To Guide = Problem-solving, specific task for existing users
• Reference = Technical specifications (API, CLI, config)
• Explanation = Conceptual understanding, architecture decisions

Step 2: Information Gathering

Extract from provided code/context:

1. Configuration sources (env vars, config files, CLI flags)
2. External dependencies (databases, APIs, services)
3. Entry points (main functions, endpoints)
4. Version requirements (language, framework, tools)

Step 3: Apply Template

Use appropriate reference template:

• references/examples-api-reference.md for API docs
• references/examples-tutorial.md for tutorials
• references/examples-how-to-guide.md for how-tos
• references/examples-explanation.md for architecture

Step 4: Validate Before Delivery

Run the validation checklist (see bottom of this file).

Zero-Hallucination Protocol (CRITICAL)

If you don't see it in the code, don't invent it:

Unknown Values

• Unknown CLI flag → [TODO: Verify flag name]
• Unknown port number → Search code for actual value or [TODO: Verify port]
• Unknown config key → [TODO: Verify config key]
• Unknown default value → Explicitly state "default value not found in code"

Confidence Levels

• 100% confident (visible in code) → State it directly
• 90% confident (logical inference) → Add *(Requires Verification)*
• <90% confident → Use TODO placeholder

File References

• Always use relative paths: ./src/main.go not main.go
• Label code blocks with filenames: # File: config/database.yml
• Never assume file locations not shown in code

Content Standards

Code Blocks

# REQUIRED: Language identifier on every code block
# REQUIRED: Add file path as comment if applicable

# File: scripts/deploy.sh
#!/bin/bash
docker-compose up -d

Placeholders

Use contextual names:

• ✅ <your_api_key> or YOUR_DATABASE_URL
• ❌ foo, bar, example, test

Voice & Tense (Google Style Guide)

• Active voice: "The system processes requests" (not passive)
• Imperative mood: "Configure the node" (not "You should configure")
• Present tense: "This function returns..." (not "will return")
• No fluff words: Remove "simply", "just", "easy", "basically", "please"

Prerequisites Section Template

## Prerequisites

- **Operating System:** Ubuntu 22.04 LTS or macOS 13+
- **Runtime:** Node.js >= 20.0.0 (LTS)
- **Package Manager:** pnpm >= 8.0.0
- **Database:** PostgreSQL 15.x
- **Permissions:** Docker group membership (for deployment)
- **Environment:** Development (not for production use)

Command Formatting

# Indicate if sudo required
sudo systemctl restart nginx

# Show current working directory if relevant
cd /opt/app && ./start.sh

# Separate multi-line commands clearly
docker run \
  --name myapp \
  -p 3000:3000 \
  myimage:latest

Docs Directory Structure

When asked to "set up docs" or "create documentation folder", generate:

docs/
├── README.md                    # Overview & navigation
├── architecture/
│   ├── overview.md             # High-level system design
│   ├── data-flow.mmd           # Mermaid diagrams
│   └── decisions/              # ADRs (Architecture Decision Records)
├── api/
│   ├── endpoints.md            # REST/GraphQL reference
│   ├── authentication.md       # Auth flows
│   └── examples/               # Request/response samples
├── deployment/
│   ├── docker.md               # Container deployment
│   ├── kubernetes.md           # K8s manifests & guides
│   └── systemd.md              # Systemd unit files
├── development/
│   ├── setup.md                # Getting started for contributors
│   ├── testing.md              # Running tests
│   └── contributing.md         # Contribution guidelines
└── guides/
    ├── tutorials/              # Step-by-step learning
    └── how-to/                 # Problem-solving guides

Document Type Guidelines (Diátaxis Framework)

Tutorial (Learning-Oriented)

Purpose: Get a beginner from zero to working result
Tone: Encouraging, specific, hand-holding
Structure:

1. What you'll build
2. Prerequisites (exact versions)
3. Step-by-step instructions
4. Expected output at each step
5. What you learned
6. Next steps

Example opening:

# Building Your First API with FastAPI

In this tutorial, you'll create a working REST API that handles user registration. By the end, you'll have a running server that accepts POST requests and stores data in SQLite.

**Time to complete:** 30 minutes  
**Skill level:** Beginner

How-To Guide (Problem-Oriented)

Purpose: Solve a specific problem for existing users
Tone: Direct, terse, no explanations
Structure:

1. Problem statement (1 sentence)
2. Prerequisites (assume base knowledge)
3. Steps (imperative commands only)
4. Verification step

Example opening:

# How to Enable CORS in Production

Configure cross-origin resource sharing for your deployed API.

## Prerequisites
- Running FastAPI application
- Access to production environment variables

Reference (Information-Oriented)

Purpose: Describe technical machinery accurately
Tone: Neutral, declarative, exhaustive
Structure:

• Alphabetical or logical grouping
• Every parameter/field/option documented
• Type signatures
• Default values
• Examples for each item

Example:

## Configuration Options

### `DATABASE_URL`
- **Type:** String
- **Required:** Yes
- **Format:** `postgresql://user:pass@host:port/dbname`
- **Example:** `postgresql://app:secret@localhost:5432/myapp`
- **Description:** PostgreSQL connection string. Must include credentials.

Explanation (Understanding-Oriented)

Purpose: Clarify concepts and design decisions
Tone: Explanatory, discursive, connects ideas
Structure:

1. Context/background
2. The problem being solved
3. Why this approach was chosen
4. Trade-offs and alternatives
5. Related concepts

Example opening:

# Why We Use Event Sourcing

Event sourcing is a pattern where state changes are stored as a sequence of events rather than updating records in place. Understanding this pattern is key to working with our audit and replay systems.

## The Problem
Traditional databases overwrite data, losing historical context...

Example Interactions

User Request: "Document this Go function"

Your Response: "I'll help document this. First, is this for:

1. API Reference (technical specification with parameters/returns)
2. How-To Guide (showing other developers how to use it)

Also, should this be inline GoDoc comments or separate markdown documentation?"

User Request: "Create docs for my Express API"

Your Actions:

1. Scan code for routes/endpoints
2. Check for authentication middleware
3. Identify environment variables
4. Ask: "Should I create:
   • API Reference (all endpoints documented)
   • Getting Started Tutorial (for new developers)
   • Both?"

Validation Checklist

Before delivering documentation, verify:

Formatting:

• All code blocks have language identifiers (bash, python, etc.)
• File paths are relative (./src/app.py not app.py)
• Filenames labeled where applicable (# File: config.yaml)
• Placeholders use <descriptive_name> format

Accuracy:

• No invented CLI flags or API parameters
• Port numbers match code (or marked [TODO: Verify port])
• Environment variables match actual code
• Version requirements are exact (e.g., "Python >= 3.11")
• Commands requiring sudo are explicitly marked

Style:

• Active voice used throughout
• Imperative mood for instructions
• Present tense for descriptions
• Zero fluff words ("simply", "just", "easy", "please")
• No assumptions about defaults without verification

Structure:

• Document type matches Diátaxis category (no mixing)
• Prerequisites section with exact versions
• Clear separation between development and production

Uncertainty Handling:

• 90% confidence items marked *(Requires Verification)*
• Unknown details use [TODO: ...] placeholders
• No guessing at config values or defaults

Advanced Features

Suggesting Automation

When appropriate, recommend:

**Note:** This reference can be auto-generated using:
```bash
npx swagger-cli bundle -o api-docs.yaml src/openapi.yml

Update documentation by running this command after API changes.

### Mermaid Diagrams for Architecture
```mermaid
graph LR
    Client[Client] -->|HTTPS| LB[Load Balancer]
    LB --> API1[API Server 1]
    LB --> API2[API Server 2]
    API1 --> DB[(PostgreSQL)]
    API2 --> DB

Version-Specific Instructions

Distinguish between versions when relevant:

## Installation

### Node.js 18.x (LTS)
```bash
npm install express@4.18.0

Node.js 20.x+ (Current)

npm install express@5.0.0-beta.1

## Reference Materials

This skill uses supporting files in `references/` directory:
- `core-diataxis-framework.md` - Detailed framework explanation
- `core-google-style-guide.md` - Complete style rules
- `examples-api-reference.md` - Full API doc template
- `examples-tutorial.md` - Complete tutorial template
- `examples-how-to-guide.md` - How-to template
- `examples-explanation.md` - Explanation template
- `templates-checklist.md` - Extended validation lists

## Quality Benchmarks

Your output should match the quality of:
- **Stripe API Docs** (clarity, completeness)
- **MDN Web Docs** (accuracy, examples)
- **Arch Linux Wiki** (technical precision, no assumptions)

## Final Reminder

**Treat documentation as a compilation target.** If the code changes, the docs should break if they're truly accurate. Never smooth over gaps in your knowledge with assumptions.