writing-for-a-technical-audience

What this skill does

# Writing for a Technical Audience

## Overview

**Core principle:** Technical writing must be clear, concise, and authentic. Clarity and technical depth are not opposites - you can have both. Avoid AI writing patterns that make content feel robotic or inauthentic.

**Why this matters:** Developers value their time. Clear documentation builds trust. AI-like writing patterns (identified through research) make content feel generic and untrustworthy. Technical depth without clarity frustrates users. Clarity without depth leaves them stuck.

## When to Use

**Use this skill when:**
- Writing API documentation or references
- Creating guides, tutorials, or how-to content
- Documenting code, features, or architecture
- Writing technical blog posts or articles
- Reviewing technical content for clarity

**Trigger symptoms:**
- "Does this sound too robotic?"
- Writing feels formal or stiff
- Using phrases like "delve into" or "leverage"
- Explaining obvious things instead of getting to the point
- Uncertain if content is clear enough

## The Three Pillars

### 1. Clarity

Developers should understand on first read. No re-reading required.

**Techniques:**
- Short sentences (15-20 words average)
- Short paragraphs (2-4 sentences)
- Active voice over passive
- One concept per paragraph
- Define technical terms on first use

### 2. Conciseness

Every word serves a purpose. Remove noise and filler.

**Techniques:**
- Delete throat-clearing ("Let me explain," "It's important to note")
- Cut hedging language ("basically," "generally speaking")
- Remove marketing fluff ("powerful," "robust," "seamless")
- Use direct language ("use" not "leverage," "show" not "illuminate")

### 3. Consistency

Same terminology, structure, and voice throughout.

**Techniques:**
- Pick one term and stick to it (not "endpoint," "URL," "route" interchangeably)
- Use consistent code formatting
- Maintain same tone across all content
- Follow established patterns for similar content types

## Avoid AI Writing Patterns

Research shows specific phrases and structures that readers identify as AI-generated. Avoid these to maintain authenticity.

### AI Phrases to Never Use

| AI Phrase | Why It's Bad | Use Instead |
|-----------|-------------|-------------|
| "delve into" | Overly formal, 269x spike post-ChatGPT | "explore," "examine," "look at" |
| "leverage" | Corporate jargon | "use," "take advantage of" |
| "robust" / "seamless" | Vague marketing adjectives | Be specific about what you mean |
| "at its core" | Condescending simplification | "fundamentally" (use rarely) or delete |
| "cutting-edge" / "revolutionary" | Empty hype | Describe actual features |
| "streamline" / "optimize" | Vague promises | "speed up," "reduce," "improve" |
| "foster" / "cultivate" | Bland corporate speak | Use direct action verbs |
| "unlock the potential" | Cliched metaphor | State specific outcome |
| "in today's fast-paced world" | Generic filler | Delete entirely |
| "needless to say" | If needless, don't say it | Delete |

### Throat-Clearing to Delete

**Never start with:**
- "Let me explain..."
- "It's important to note that..."
- "It's worth noting..."
- "In essence..."
- "Let's explore..."

**Fix:** Start with substance. Delete the preamble.

### Hedging Language to Eliminate

| Hedged | Confident |
|--------|-----------|
| "I think we should..." | "We should..." |
| "It would be great if..." | "Please do X" |
| "Should be able to..." | "Can complete..." |
| "Basically..." | Delete it |
| "Generally speaking..." | Be specific or remove |
| "One might argue..." | "This indicates..." |

**Why hedging fails:** Makes you sound uncertain even when you're correct. State facts directly.

### Transition Word Overuse

AI defaults to formal Victorian-era connectors. Use simpler alternatives or break paragraphs.

| Overused AI | Better |
|------------|--------|
| Moreover / Furthermore | Plus, also, and |
| However / Nevertheless | But, though, still |
| Additionally | And, plus |
| Consequently / As a result | So, then |
| That being said | But (or delete) |
| Indeed / Interestingly | Often delete entirely |
| In conclusion | End cleanly without announcing it |

## Technical Writing Patterns

### Explain WHY for These Cases

**ALWAYS explain why when:**

1. **Design decisions with tradeoffs**
   - Good: "We use pagination instead of cursors because it's simpler for most use cases and maintains consistent ordering"
   - Bad: "We use pagination" (no context for when to deviate)

2. **Non-obvious patterns**
   - Good: "Row Level Security must be enabled on all tables exposed via the Data API because it enforces security at the database level, preventing bypass through direct SQL access"
   - Bad: "Enable RLS on all tables" (why?)

3. **Breaking from conventions**
   - Good: "This API uses POST for reads because GET requests can't include request bodies in some HTTP clients"
   - Bad: "Use POST to fetch data" (violates REST conventions without justification)

**When "how" alone suffices:**
- Mechanical steps with no alternatives ("Click Save")
- Standard practices ("Use npm install")
- When you genuinely don't know why (document behavior, note uncertainty)

### Code Examples: One Excellent Example

**Don't:**
- Implement in 5 languages
- Create fill-in-the-blank templates
- Write perfect-world examples with no error handling

**Do:**
- One complete, runnable example
- Include error handling
- Show realistic usage
- Comment WHY, not what

**Good Example Pattern:**

```python
# Good: Complete, realistic, explains why
try:
    response = await fetch_user(user_id)
    # Check status before assuming success - API returns 200 for "not found"
    if response.status != 200:
        raise APIError(f"Failed to fetch user: {response.status}")
    return response.json()
except NetworkError as e:
    # Network failures are retryable - log and re-raise for retry logic
    logger.warning(f"Network error fetching user {user_id}: {e}")
    raise
```

**Bad Example Pattern:**

```python
# Bad: Perfect world, no context, brittle
response = await fetch_user(user_id)
return response.json()
```

### Progressive Disclosure

Layer complexity. Simple first, then depth.

**Pattern:**
1. **Basic explanation** - what it does, core concept
2. **Simple example** - minimal working code
3. **Advanced section** - edge cases, configuration, tradeoffs
4. **Reference** - complete API surface

**Good:**
```markdown
## Authentication

All API requests require an API key in the Authorization header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/users
```

### Advanced: Token Rotation

For production systems, rotate API keys every 90 days...
```

**Bad:**
```markdown
## Authentication

Authentication can be performed using several methods including API keys, OAuth 2.0, or JWT tokens. The choice depends on your security requirements, user experience goals, and architectural constraints. Let's explore each option...
```

(Too much upfront. Start simple.)

## Anti-Patterns from Real Documentation

### 1. Assumes Too Much

**Bad:**
> "Simply connect your ETLOrchestrator to the HydraNode endpoint. Once a connection is established, instantiate a DataStream by passing your KinesisConfiguration."

**Why it fails:** Jargon firehose with no definitions, no links, no onramp for beginners.

**Fix:** Define terms, link to prerequisites, provide Getting Started guide.

### 2. Perfect World Examples

**Bad:**
```javascript
const myFile = document.getElementById('file-input').files[0];
const response = await uploadFile('/api/upload', myFile);
console.log('File uploaded successfully!');
```

**Why it fails:** No error handling, ignores edge cases (no file selected, network failure, file too large).

**Fix:** Wrap in try-catch, check response status, handle undefined files.

### 3. Vague and Unhelpful

**Bad:**
- `getUser(userId)`: "Gets a user by their ID."
- `class DataProcessor`: "A class for processing data."
- `processData(data)`: