technical-writing-for-engineers

What this skill does

# Technical Writing for Engineers

## Author Profile

**Audience**: Senior engineers, principal/staff engineers, tech leads —
distributed systems practitioners. They are busy, skeptical, and will
stop reading the moment they sense filler or obvious advice.

**Voice**: First-person, direct, intellectually honest. Use "I think",
"we decided", "we got this wrong", "I'd do X differently now". Avoid
the royal "we" for one-person opinions. Never hide behind passive voice
when you made a call.

**Topics**: Backend engineering, software architecture,
business/engineering intersection, distributed systems trade-offs.

---

## The Story Frame

Every post follows a **Before → Journey → After** arc.

- **Before**: What was broken, missing, or unclear? What did it cost? Who felt it?
- **Journey**: What did we try? What surprised us? What did we get wrong first?
- **After**: What did we land on? What would we change? What do we now believe?

This arc is not optional. If a section doesn't serve one of these three
phases, cut it or fold it into one that does.

---

## Hook Rule

**The hook is the first ~150 words. It is the most valuable real estate in the post.**

The hook must contain:
1. The problem or gap — stated directly, not implied
2. The stakes — what goes wrong if this isn't solved
3. A signal of who this is for

Context, background, and definitions come **after** the hook. Never before.

**Hook template:**
> [System/situation] had a gap. [What the gap caused]. Here's how we thought through it.

**Good hook example:**
> Our order anomaly detector was flagging healthy orders as undeliverable —
> silently. No alert, no log, just a customer wondering where their package
> was. We needed a way to catch these at decision time, not after the fact.
> Here's the model we built and the three approaches we rejected before
> landing on it.

**Complete example (hook + outro + title):**

```markdown
Our order anomaly detector was flagging healthy orders as undeliverable — 
silently. No alert, no log, just a customer wondering where their package 
was. We needed a way to catch these at decision time, not after the fact. 
Here's the model we built and the three approaches we rejected before 
landing on it.

[Journey section: What you tried, what surprised you, what you got wrong]

If I were starting this again, I'd resist the urge to build the model 
first. The hardest part wasn't detection — it was agreeing on what 
"anomaly" meant to the business. That conversation took longer than the 
code. Next time I'd run it in week one.

How We Built Anomaly Detection Without False Positives
```

**Bad hook (do not write this):**
> In distributed systems, reliability is a key concern. Many teams face
> challenges when it comes to detecting anomalies. This post will explore
> some approaches to this problem.

---

## Structure Checklist

Before drafting, answer these in order:

1. **Reader profile** — Who is the one person reading this? What do they
   already know? What are they trying to solve?
2. **Before/pain** — What is the concrete pain? Quantify if possible
   (latency, error rate, manual hours, customer impact).
3. **Hook draft** — Write the opening 3–5 sentences before anything else.
   Rewrite until it earns the next paragraph.
4. **Necessary context** — What does the reader need to understand the
   journey? No more than needed. If it's longer than 3 paragraphs, it's
   probably a separate post.
5. **Options and trade-offs** — What did you consider? Why did you reject
   the alternatives? Be honest about the weaknesses of what you chose.
6. **Conclusion / so-what** — Your take. Not a summary. What would you do
   differently? What do you now believe about this class of problem?
7. **Title last** — Write the title after the post exists. Make it
   descriptive and tech-specific. No clickbait.

---

## Formatting Rules

- **Headers**: Use H2 for major sections, H3 for subsections. Headers
  should name what the section *does*, not just what it *is*. "Why we
  rejected the queue-based approach" beats "Alternative Approaches".
- **Paragraphs**: 3–5 lines max. If a paragraph runs longer, split it.
- **Lists**: Use for parallel items (options, trade-offs, steps). Don't
  use lists to avoid writing prose.
- **Code blocks**: Include early if the post is technical. A reader who
  sees real code in the first scroll trusts the post is concrete.
- **Active voice, present tense**: "The service processes the request"
  not "the request is processed by the service".

---

## Banned Patterns

Never write these:

| Pattern | Why |
|---|---|
| Opening with a definition ("Distributed systems are...") | Signals no hook, loses the reader |
| Pure reference sections with no narrative | Reads like docs, not a post |
| Ending on a link ("See the RFC for details") | Abandons the reader; your take belongs at the end |
| Passive voice at key decision moments | Obscures who made the call and why |
| "In this post, we will cover..." | Wastes hook space; show don't announce |
| Vague scope phrases ("there are many ways to...") | Filler; commit to a perspective |

---

## Banned Words

Do not use: `just`, `simply`, `obviously`, `of course`, `easy`,
`everyone knows`, `very`, `basically`, `turns out`, `in order to`.

These words either condescend to the reader or pad the sentence. Cut them entirely.

---

## Outro Rule

**End with your take — not a summary.**

The outro is not a recap of what you wrote. It is your honest current
belief about the problem, what you'd do differently, or what you'd want
a reader to walk away thinking about.

Ask yourself: *If a colleague asked me "so what's the takeaway?" over
coffee, what would I actually say?* Write that.

**Bad outro:**
> In this post we covered the anomaly detection model, the three approaches
> we considered, and how we landed on a threshold-based system.

**Good outro:**
> If I were starting this again, I'd resist the urge to build the model
> first. The hardest part wasn't detection — it was agreeing on what
> "anomaly" meant to the business. That conversation took longer than the
> code. Next time I'd run it in week one.

---

## Title Guidelines

Write the title last. A good title is:
- **Specific**: names the technology, system, or problem
- **Honest**: matches what the post actually delivers
- **Not clickbait**: no "You won't believe", no "The ultimate guide"

Formats that work well:
- `[Problem] without [trade-off you'd expect to accept]`
- `Why we chose [X] over [Y] for [Z]`
- `How [system] handles [hard thing]`
- `[Concrete thing] taught me [non-obvious insight]`