Skip to main content

Editing for Clarity: Before and After

What This Concept Is​

Editing is not proofreading. Editing is cutting the first draft by 30-40% without losing any information and then making the remaining text shorter, more specific, and more testable.

The core moves:

  • delete anything that hedges without adding information ("it's important to note that...")
  • replace adjectives with numbers ("very fast" -> "60ms p95")
  • replace nominalizations with verbs ("made a decision to implement" -> "implemented")
  • collapse paragraphs where two sentences say the same thing
  • cut opinions you cannot defend from an interview

A clean edited draft reads faster, feels more honest, and survives hostile reading.

There is a deeper principle underneath these tactics: every sentence is either earning its place or costing the reader. Fillers do not read as neutral -- they actively reduce the perceived density of the rest of the document. A paragraph with two strong sentences and three filler sentences reads as weaker than the same paragraph with the fillers removed, because the strong sentences are no longer diluted by the surrounding soup.

Editing is also a skill that travels. The same moves that tighten a blog post tighten an ADR, a PR description, an incident report, a design doc, a Slack message to leadership. Learning to edit well is not "writing advice"; it is one of the highest-leverage career skills in software, because almost everything senior engineers do is mediated by writing.

Why It Matters Here (In the Capstone)​

Every artifact you will produce in Module 5 -- case study, bio, README, blog post, ADR -- lives or dies at the edit stage. First drafts almost always have the same disease: padded, hedged, abstract. Editing is how you turn them into prose another engineer will actually read.

The compounding effect: once you internalize editing moves, you write tighter first drafts automatically, which lets you publish more often for less effort. The quarterly cadence from concept 08 is unsustainable without the editing discipline from this concept; the two work together or neither works.

Concrete Example: Before and After​

Before (107 words):

"One of the things that was really interesting during the capstone project was the decision around how to handle idempotency for the various different incoming data feeds, which had somewhat different delivery semantics. After a lot of thought and iteration, I ended up deciding that it would probably be best to implement a deduplication mechanism that utilized a combination of Redis for the short-term cache and Postgres for the long-term uniqueness constraint. This turned out to work pretty well, although there were definitely some tradeoffs involved that I'll talk about below."

After (42 words):

"The three feeds had different delivery semantics. I enforced idempotency with a 24-hour Redis dedupe window backed by a unique index on (source, external_id) in Postgres. It works; the main cost is operator complexity -- two systems to reason about."

The second version loses nothing. The reader now has the specific design, the specific cost, and the specific tradeoff, in a third of the words.

Concrete Example: The Weasel-Word Audit​

Run this exact list against your next draft. Each hit is almost always cuttable.

Weasel phraseCut or replace with
"it's important to note that"(delete)
"as mentioned above"(delete; the reader knows)
"at the end of the day"(delete)
"basically" / "essentially"(delete)
"very" / "really" / "quite"(delete the qualifier; strengthen the noun)
"a number of""five" / "twelve" (a specific count)
"robust" / "scalable" / "efficient"a measurement or a named property
"made a decision to""decided to" -> "I implemented"
"I think that"(delete unless uncertainty is the point)
"in order to""to"

A 2,000-word draft commonly loses 150-300 words to this list alone, without touching structure.

Common Confusion / Misconceptions​

Editing is not "making it sound better." Cosmetic edits are the lowest-value kind. The high-value edits are structural: cutting entire sentences, merging paragraphs, replacing vague claims with specific ones.

Editing should happen while drafting. No. Drafting and editing use different mental modes. Draft ugly; edit separately; often on a different day. Trying to do both at once produces slow, over-hedged first drafts.

Hedging is humility. It is not. "I think maybe it could be the case that..." reads as unsure, not polite. Cut the hedge. State the thing. If you are actually unsure, say "I'm not sure" in one short sentence and move on.

Editing is optional for internal documents. ADRs, design docs, and incident writeups travel further than you expect -- they end up in interviews, promotions, and mid-incident Slack threads. The same edit discipline applies whether an artifact is "public" or not.

How To Use It (In Your Capstone)​

Use this three-pass edit on any artifact before shipping:

  1. Structural pass -- for each paragraph, ask "what is the point?" If none, delete. If duplicate of another paragraph, merge.
  2. Sentence pass -- replace abstract claims with concrete ones (numbers, examples, names). Cut filler phrases.
  3. Word pass -- replace adjectives with facts. Replace nominalizations with verbs. Cut every "very."
  4. Read-aloud pass -- if a sentence is hard to say, it is hard to read.
  5. Hostile-read pass -- imagine a peer who dislikes your writing. Which sentence would they underline as weakest? Replace it.
  6. Before/after snapshot -- save the pre-edit draft as foo.draft.md and the post-edit version as foo.md. The diff is the artifact.
  7. Ship -- once the word count has dropped by ~30% and every remaining sentence is defensible.

Check Yourself​

  1. Find the last thing you wrote. Can you delete one paragraph with no information loss?
  2. Count the "very," "really," "basically" in it. What is the count?
  3. For every strong claim, is there a number or example directly after it?
  4. Did the draft lose ~30% of its words during editing? If less, the cut was not aggressive enough.
  5. Does every remaining sentence pass the "could I defend this live?" check?
  6. If a reviewer underlined the weakest sentence, would you agree with them?

Mini Drill or Application (Capstone-scoped)​

Three drills:

  1. 200-word kata. Take any 200-word section from your capstone case study draft. In 15 minutes: cut it to 120 words maximum, replace at least two adjectives with numbers, cut at least three hedge phrases, read aloud to confirm it flows.
  2. Weasel-word pass. Run the weasel table above against an existing ADR. Count hits before and after. File both versions under library/raw/writing/ as a paired example.
  3. Hostile-read exchange. Trade one 500-word draft with a peer from the program. Each of you underlines the five weakest sentences in the other's draft. Rewrite those five. Do not argue; the underlines are the signal.

Keep the before/after pairs in your portfolio repo under library/raw/writing/ -- they are legitimate artifacts showing you can edit your own work.

Transfer / How This Synthesizes Prior Semesters​

Editing moves learned here apply to every written artifact the rest of your career produces, and those moves are echoes of disciplines from earlier in the degree:

The transferable meta-move: write ugly, edit separately, on a different day. Attempting to draft and edit simultaneously produces slow, hedged first drafts and no visible final edits; separating the modes is the highest-leverage writing habit in the degree.

See also (integrative)​

Source Backbone​

Portfolio assessment packages evidence from the whole curriculum. These books provide the technical and professional backbone for the narrative.