Writing as an Engineering Skill — What Design Docs, Postmortems, and Review Comments Actually Do

• Why This Comes Before Promotion
• What Writing Does Inside an Organization
• Design Docs — What Survives Is the Rejected Alternatives
• Postmortems — Separate Fact From Interpretation
• Review Comments — Grading Them Reduces Conflict
• What Gains Value as Writing Gets Cheap
• Try It This Week
• Further Reading
• Sources

Why This Comes Before Promotion

Advice about engineers and writing usually ends the same way: write well and your work gets recognized at review time. Not wrong, but the order is inverted.

Put the order right and it reads like this. Writing is first a device for verifying your own thinking. Then it is a tool for creating a surface an organization can argue against. And as a consequence of those two, it moves evaluations. Approach it from the third item alone and the document becomes promotional material, which organizations discount fast.

The first item is the core. A design you cannot explain is usually a design you have not understood. What felt smooth in your head reveals its holes the moment it becomes sentences. So writing, before it is an expressive skill, is an inspection of your own comprehension.

What Writing Does Inside an Organization

Three things.

One is asynchronous scale. A meeting multiplies time by attendees; a document costs the author no more when readers are added. Ten people in a one-hour meeting is ten hours. The same content as a document is two author hours plus fifteen minutes each for nine people.

Another is time travel. A document speaks to whoever arrives three years from now. What that person wants is not what got built but why it got built that way.

The third matters most. Writing creates a surface that can be argued against. A claim made out loud has to be rebutted on the spot, and the loudest voice usually wins. A claim on a page can be examined on each reader's own time, with a considered objection brought back. A good document is not a tool for getting your position through; it is a tool for finding out quickly when your position is wrong.

Design Docs — What Survives Is the Rejected Alternatives

Most of a design doc goes stale. Diagrams change, interfaces shift, schedules miss. Almost one thing holds value three years out: the alternatives you rejected and why.

The reason is the one from part 3. Code shows the adopted option and not the alternatives. So a newcomer says "why not just do it this way," repeatedly, and that way was usually already considered and dropped.

One more thing has to be marked: the one-way doors. Data formats, publicly exposed interfaces, storage choices — anything whose cost of change rises sharply later — should be visibly separated in the document. With the marking, reviewers know where to spend their attention. Without it, review time goes entirely to arguing about reversible things.

Postmortems — Separate Fact From Interpretation

The most common failure in an incident report is mixing fact and interpretation inside a single sentence. "The outage happened because the cache configuration was wrong" fuses an observation to a causal claim, and fused together neither gets verified.

Separated, it goes like this. Facts get written in time order only: at what minute which alert fired, what was confirmed, what was done, when recovery landed. Interpretation goes in its own section, and each interpretation names the facts it rests on. Readers who disagree with your interpretation can still share your facts.

Attached to this is the principle of writing blamelessly. The Google SRE book defines it as assuming everyone involved had good intentions and did the right thing with the information they had. And it gives the reason as practical rather than moral: in an atmosphere of blame, issues do not come to light and get swept away, which raises the risk carried by the organization. The same chapter sums the principle up by noting that you cannot fix people but you can fix the systems and processes that support them.

This is an information-gathering problem, not a manners problem. In a report where blame is expected, people do not describe precisely what they did, and no improvement can be designed on top of imprecise facts.

Review Comments — Grading Them Reduces Conflict

A large share of review friction comes from the weight of a comment not being transmitted. The author receives every comment as a demand; the reviewer thought they were making a light suggestion.

The fix is simple: grade each comment.

Example — three markers to put in front of a comment

[blocking]   merging as-is causes a problem. basis: balance goes negative under concurrent requests
[suggestion] this would read more easily done this way. mergeable without changing it
[taste]      I would write it differently, but this is not a right-or-wrong matter

That one marker cuts review time considerably. The author knows what to answer first, and a taste comment stops delaying a merge.

On content there is one rule: write observations and grounds, not demands. "Change this" is worse than "if two concurrent requests arrive, the balance looks like it goes negative here — is that right?" The second leaves open the possibility that the reviewer is wrong, and leaving it open ends the conversation quickly on the occasions when they are.

What Gains Value as Writing Gets Cheap

Here is the part to be honest about. Producing sentences got noticeably cheaper. So the scarcity of a well-written document is not what it was.

What remains, then? Two things, as far as can be told. One is the judgment about what to write: knowing which parts of this decision are irreversible, which alternatives were real competitors, and which facts you still do not have is a different capability from producing prose. The other is the signature. Who has their name on the document and carries the consequences of the decision does not delegate.

That said, this part is hard to say with confidence. How organizations will treat documents, and how the weight of a signature actually shifts, is unsettled. What can be said now is that producing sentences definitely got cheaper, and verifying the judgment those sentences carry did not.

Try It This Week

Pick one technical decision you made recently and write three paragraphs about it: the option adopted, two alternatives you considered and dropped with the reason, and the part of this decision that is hard to reverse. Half a page is enough, and if it takes more than thirty minutes, the decision is not yet settled in your own head.

• Problem-Solving Trainer — restating a problem in your own words is the first of the nine moves, which is exactly the job the opening paragraph of a design doc does.

Where this does not apply: in an organization where decision-makers do not read documents, a long document does nothing. There it is better to compress it into a one-page summary readable five minutes before the meeting, and keep the long version only as a record for whoever arrives later.

Further Reading

• Related post on this blog: Persuasive Writing — The Structure That Gets Design Docs and RFCs Approved

What Stays Expensive series

• Previous: Designing Verification — Tests as Grounds for Trust, Not Pass or Fail
• Next: Framing the Problem — How to Avoid Perfectly Solving the Wrong One

Sources

• Postmortem Culture — Google SRE Book — the definition of a blamelessly written postmortem as assuming everyone had good intentions and did the right thing with the information they had, the argument that an atmosphere of blame gets issues swept under the rug, and the point that you cannot fix people but can fix systems and processes. Read 2026-08-15.
• The comment grading markers and the priority ordering for design docs are not from that source; they are the approach assembled in this post.