Preface

Who this book is for

You are good at something hard. You can derive the result, ship the feature, run the assay, build the model. And then someone asks you to write it up, and the page sits there, and the version that lands on it is somehow worse than the version in your head.

This book is for you. Specifically, it is for the STEM undergraduate writing a first lab report, the graduate student facing a thesis that will take two years, the working engineer whose promotion now depends on a design doc rather than the design, the data scientist trying to convince a VP who will never read the methodology, the researcher up against a peer reviewer, the developer staring at a README that nobody can install from, and the scientist who wants the public to understand what the public is paying for. It is for anyone who has been told, in a meeting or a margin comment, that their work is "too technical." That phrase is rarely a compliment, and it is almost never about the technical content. It is about the writing.

You do not need a background in writing to start. You need work worth explaining and a willingness to revise.

The one idea everything else hangs on

Most people treat writing as transcription. You do the thinking — the real work — and then you "write it up," copying finished thoughts onto the page the way you'd copy numbers off an instrument. On that view, writing is clerical. It comes last. It can be rushed.

That view is wrong, and it is the reason so much technical writing is bad. Here is the idea this entire book is built on:

You do not know what you think until you try to write it down.

The act of putting an idea into a clear sentence is the act of discovering whether you actually have one. Vague understanding survives in your head because your head lets it cheat — it fills gaps with hand-waving, holds three half-contradictory versions at once, and never forces a commitment. A sentence does not allow that. To write "X causes Y because Z," you must decide whether Z is true, whether it is the reason, and whether X really causes Y or merely accompanies it. Writing is where fuzzy thinking gets caught.

This has a blunt corollary, and it is the test you will return to all forty chapters: if you can't explain it clearly, you don't understand it yet. The muddled paragraph is not a writing problem to be polished away. It is a thinking problem wearing a writing costume. Fix the thinking and the prose follows; polish the prose without fixing the thinking and you get fluent nonsense, which is worse, because now it's persuasive.

So this book teaches two skills at once and refuses to separate them: how to think clearly about a technical subject, and how to communicate that thinking to one specific reader. They are the same skill seen from two sides.

Why this book is broader than the technical-writing book you remember

The classic technical-writing course teaches formatting. Here is the layout of a memo; here are the five sections of a report; here is where the abstract goes. Students leave with templates and a vague sense that good writing is correct writing. They learn to fill in forms. They do not learn to think on paper, and they are unprepared the first time the form doesn't fit.

This book covers the conventions — you will learn IMRaD, the specific-aims page, RFC 2119, and the rest — but conventions are the easy part, and they are not the point. The point is the judgment underneath them: who is reading, what they need, what to cut, how to structure so a busy person finds the answer in ten seconds.

It is also broader in scope than the older texts, because the job changed. A modern technical professional does not just write reports and papers. You write code comments and docstrings; READMEs and API references; tutorials and runbooks; data memos and dashboard copy; pull-request descriptions, bug reports, and postmortems; Slack threads that function as decisions; blog posts that explain your work to strangers; and, increasingly, you write with a large language model and have to keep your own judgment in the loop. A book that stops at the lab report has stopped at about 1995. This one carries the same core principles — audience, clarity, structure, revision — across that whole modern landscape, into software and data and AI-assisted drafting, because the principles do not change when the format does. That is the entire bet: learn the thinking once, apply it everywhere.

How the teaching works: examples are not decoration

You cannot learn writing from rules. "Be concise" is true and useless; it tells you the destination, not the road. You learn writing by watching weak prose become strong prose and seeing exactly what changed and why.

So that is how this book teaches. The engine of nearly every chapter is the before/after transformation: a real-looking weak passage, a precise diagnosis of what's broken, the revision, and a short note on the principle and the payoff — often quantified, because "15 words, 7 words, same meaning" is more convincing than "tighter."

❌ Before: The implementation of the proposed methodology was undertaken subsequent to the completion of the initial phase. (15 words, no information)

✅ After: We started testing after the initial investigation. (7 words, same meaning, half the reading time)

Why it's better: Real verbs ("started," "testing") replace nominalizations ("implementation," "completion"); the sentence names a doer. That is not dumbing down. It is cleaning up. Clarity is not the enemy of precision — jargon is.

When you read those pairs, do not skim to the "after." The learning is in the gap. Cover the fix, try your own, then compare. The examples are the instruction; the surrounding prose just points at what to notice.

One more thing about the examples, and about this book in general. A technical-writing textbook that is itself badly written is a contradiction in terms, so this one tries to practice what it preaches on every page. Where it succeeds, the writing will be nearly invisible and you'll think about the ideas. Where it fails, you have my permission to mark it up. Reading as an editor is a skill too, and we cover it in Chapter 12 and Chapter 39.

What this book will not do

An honest preface sets limits.

This is not a grammar course from zero. It assumes you can write a correct English sentence and targets the specific errors that plague technical writing — buried subjects, runaway nominalizations, the passive voice used to dodge responsibility — not the parts of speech. (If your grammar is shaky or English is not your first language, you are still welcome here; see Prerequisites, where I make the case that this book is, if anything, more useful to you.)

It will not make writing effortless. Nothing will. Good writers are not the ones for whom it comes easily; they are the ones who have made peace with the fact that it doesn't.

And it will not let you out of revising. This is the promise people most want and the one I won't make. First drafts are supposed to be bad — that is what a first draft is for. The quality you admire in finished writing was put there in the second, third, and fourth passes. A book that promised great writing without revision would be lying, and lying is the one thing a book about clear communication cannot do.

An invitation

Writing well is learnable. It is not a talent you were born with or without; it is a craft, and like any craft it yields to deliberate practice. The people who write clearly are not smarter than you. They have simply done the reps — drafted badly, cut hard, asked "who is reading this," and revised one more time.

This book is the reps, organized. Pick the track that fits your work (the next two pages show you how), do the exercises rather than just nodding at them, and build the portfolio as you go. By the end you will not write perfectly. You will write clearly, on purpose, for a reader you can name — which turns out to be most of the job, and is far rarer than it should be.

Open to Chapter 1. Let's figure out what you think.