Technical Writing for People Who'd Rather Write Code

You didn't become a developer to write documents. But you spend a significant portion of your time writing: PR descriptions, commit messages, design docs, Slack messages, README files, incident reports, code comments, and emails to stakeholders who don't know what a "microservice" is.

Bad technical writing wastes time — other people's time. A vague PR description costs the reviewer 20 minutes of confusion. An unclear design doc generates a 30-minute meeting to clarify what the document should have communicated. An ambiguous Slack message spawns a 15-message thread of "what do you mean by...?"

Good technical writing isn't literary talent. It's a set of principles that make your communication clear the first time.

The Core Principle: Write for the Reader

The most common writing mistake: writing for yourself. You know the context, the constraints, the background, the decisions. The reader doesn't. They're encountering your writing cold, without any of the context in your head.

Before you write anything, ask: "Who will read this, and what do they need from it?"

A PR description is read by a reviewer who needs to understand what changed and why. A design doc is read by teammates who need to evaluate an approach. A README is read by someone who's never seen the code and needs to get started. An incident report is read by people who want to understand what happened and prevent it from happening again.

Each audience needs different information at different levels of detail. Write for them, not for you.

Five Principles That Cover 90% of Technical Writing

1. Lead With the Point

Don't build up to your conclusion. Start with it.

Bad: "We've been evaluating several options for the caching layer. After considering Redis, Memcached, and an in-memory cache, taking into account our consistency requirements, operational overhead, and team familiarity, we've decided to go with Redis."

Good: "We're using Redis for the caching layer. It fits our consistency requirements and the team already knows it. Here's the full evaluation."

The reader gets the answer in the first sentence. If they want the reasoning, they keep reading. If they trust your judgment, they're done. Both paths work.

2. Use Short Sentences

Long sentences with multiple clauses, parenthetical explanations, and stacked prepositional phrases force the reader to hold too much in working memory while trying to extract the point, which gets buried under the weight of the sentence structure itself.

That sentence made its own point. Break it up:

"Long sentences force the reader to hold too much in working memory. The point gets buried. Break complex ideas into separate sentences."

Short sentences are easier to read, easier to translate for non-native English speakers, and easier to scan. There's no technical writing scenario where longer sentences are better.

3. Eliminate Weasel Words

Weasel words hedge without adding information. "Basically," "somewhat," "arguably," "it seems like," "to some extent," "relatively."

Bad: "The service is somewhat slow, arguably due to the database queries, which are relatively unoptimized."

Good: "The service responds in 800ms. The database queries account for 600ms. They lack indexes on the filtered columns."

The second version is specific and actionable. The first version is vague and hedged. If you're not sure, say "I'm not sure" — that's more honest and more useful than hiding uncertainty behind qualifiers.

4. Use Concrete Examples

Abstract explanations are hard to follow. Concrete examples make them easy.

Abstract: "The service should handle concurrent requests to the same resource gracefully."

Concrete: "If two users update the same order at the same time, the second update should fail with a 409 Conflict rather than silently overwriting the first."

The abstract version requires the reader to imagine what "gracefully" means. The concrete version shows them.

5. Structure for Scanning

People don't read technical documents front to back. They scan for the section that answers their question. Help them by structuring for scanning:

• Headers that describe the content (not clever, descriptive)

• Bullet points for lists of items

• Bold for key terms and important points

• Code blocks for anything that's code or command-line

• Short paragraphs (3-5 sentences max)

A wall of unbroken text says "this will take effort to extract information from." Structured formatting says "here's where to find what you need."

Specific Formats

PR Descriptions

A good PR description answers three questions:

1. What changed? (One sentence summary)

2. Why did it change? (The motivation — a bug, a feature, a refactor)

3. How should the reviewer look at it? (Where to start, what to focus on, what's not changing)

## What
Add retry logic to the payment processing service.

## Why
Payment API calls fail intermittently (~2% of requests) due to
upstream timeouts. Currently these fail permanently and require
manual retry. This adds exponential backoff with 3 retries.

## Review Notes
- Start with `PaymentClient.cs` — that's where the retry logic lives
- `RetryPolicy.cs` is the generic retry implementation
- Tests cover the backoff timing and max retry count

Commit Messages

The first line is a summary (imperative mood, under 72 characters). If more context is needed, add a blank line and then a body.

Add retry logic for payment API calls

Payment API returns 503 intermittently (~2% of requests).
This adds exponential backoff (1s, 2s, 4s) with a max of 3
retries before failing permanently.

Closes #1234

"Fix bug" and "Update code" are not commit messages. They're timestamps.

Design Documents

Structure: Problem, Proposed Solution, Alternatives Considered, Tradeoffs, Open Questions.

The "Alternatives Considered" section is the most valuable part. It shows you've thought beyond the first idea and gives readers context for why this approach was chosen over others. Without it, readers generate their own alternatives and ask about them in review — wasting everyone's time.

Key Takeaway

Technical writing is about clarity, not talent. Lead with the point. Use short sentences. Replace vague language with specific details. Use concrete examples. Structure for scanning. And always write for the reader — their context, their questions, their time. Every minute you spend making your writing clear saves ten minutes of other people's confusion.