What's Left to Craft: Editing a draft that wasn't yours

Ask most people what a technical writer does, and the answer is always some version of the same thing: writes. At a past job, I asked a product manager for information I needed to actually write something. Their response, in what one might call “an all-caps tone,” was that because I’m a technical writer, my job is to write. We’ve found ourselves in an era where words can be generated from nothing. (It’s called a hallucination, by the way.) And copy that started with a human draft can read as complete while carrying the same problems it always has, such as unexplained context.

That assumption isn’t new. Editing a draft that wasn’t yours was never just about fixing the words already on the page. It’s about knowing what’s missing before you can fix anything. So what does a writer still do to a draft, especially one that’s already had a line level pass for grammar, spelling, and structure?

Read for density, not fluency

A sentence can be grammatically complete and still say nothing. That’s harder to catch than a typo, because nothing about the sentence signals a problem. It reads fine. It survives a spellcheck, a grammar pass, even a confident first read.

A colleague recently pointed me to a prereqs section, written as a paragraph instead of a list, that repeated “fine-grained permissions” three times without ever naming which ones. Something like:

Before you begin, make sure you have fine-grained permissions configured for your account. You’ll need fine-grained permissions to access billing data and fine-grained permissions to view cost reports. If you don’t have the appropriate fine-grained permissions, contact your administrator.

“Fine-grained permissions” is real terminology, not filler, which is exactly why it slides past a first read. Repeated three times without ever naming an actual permission, it tells a reader nothing they can act on. What was needed was the actual IAM actions:

Before you begin, confirm your role includes billing:ViewInvoices to access billing data and reports:ViewCostReports to view cost reports. Ask your administrator to grant these if you’re missing them.

Same length. Same level of technical vocabulary. The difference is whether a reader can act on it without going to find the answer somewhere else.

Understand the reader’s context, not the author’s

An engineer’s setup instructions can be entirely accurate and still be useless to the person reading them if the author never had to imagine a reader without their own access.

I once got DNS setup instructions that read something like this.

Create a new record pointing to the service endpoint using Meridian.

Meridian meant something inside the company. It was a proper noun, not a description, so nothing about the sentence signaled that it needs translating. However, it says nothing to an external reader, who’s never heard of Meridian and needs to do this in Route 53, Cloudflare, or whatever DNS provider they actually have. What the instructions needed was this:

Create a CNAME record with your DNS provider pointing to [service endpoint].

The same pattern shows up anywhere insiders stop noticing their own vocabulary. Resource limits go unmentioned because the person who wrote them had effectively unlimited access and never hit the ceiling a normal account would. A feature’s project code name gets dropped into a draft the way a team says it out loud in standup, with no acknowledgment that a reader outside that room has no way to know what it refers to.

Verify before you inherit the confidence

A sentence’s confidence doesn’t tell you whether it’s accurate. Fluency and correctness are independent of each other, so a wrong sentence about how a system behaves can be perfectly worded and still wrong. Reading closely catches density and context problems. It doesn’t always catch this one. Accuracy has to be checked against something outside the page.

For anything that describes real system behavior, I don’t take a draft’s word for it, mine, a colleague’s, or a model’s. I check the UI myself in a staging environment. I pull the latest SDK and OpenAPI spec directly, and I run tests against the actual code when I can. I also pull Jira tickets and PRDs, but I read them as intent, not fact. A ticket describes what someone wanted to happen. A staging environment shows what’s actually happening. When those two disagree, I find out which one is true before I write anything based on either.

Reorder around what the reader needs first, not what the source gave first

A draft’s order often reflects how it was written, not what a reader needs first. I once inherited a document where the same prerequisites were restated inside nearly every section instead of being stated once, up front. Each restatement was worded slightly differently, so it wasn’t always clear whether it was the same prerequisite or something new. When the author got tired of repeating them, they started linking to earlier steps instead, and those links broke every time a step got renumbered. By the time it reached me, references pointed to the wrong places, the numbering was off, and prerequisites were scattered across the entire document instead of living in one place a reader could check before starting.

Reordering fixed most of it. Prerequisites moved to a single section at the top. Steps were resequenced into the order a reader would actually follow, not the order they’d been drafted in. The document went from around 200 pages to 90, mostly by putting each piece where a reader needed it instead of wherever it had landed when it was written.

The test isn’t whether the information is all there. It’s whether it’s in the order a reader would actually need it, not the order it was easiest to draft in.

This is writing, whether the draft in front of you came from a colleague, a model, or pieced together line-by-line through your research. That’s what’s left to craft, no matter where the draft came from.