/writing-for-a-technical-audience

name: writing-for-a-technical-audience
description: Use when writing documentation, guides, API references, or technical content for developers - enforces clarity, conciseness, and authenticity while avoiding AI writing patterns that signal inauthenticity
user-invocable: false

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:**

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