writing-for-a-technical-audience

# 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 Wr