Scrolls
5 min read
On this page

The Self-Editing Checklist

Most technical writers skip editing or do it haphazardly — reading through once, fixing a few typos, and calling it done. That is not editing. Real self-editing is a systematic process with multiple passes, each focused on a different dimension of quality. This checklist gives you a repeatable system: structure check, clarity check, jargon check, length check, and "so what?" check. Run through all five, and your document will be dramatically better than the first draft. One more rule: do not edit the same day you write. The 24-hour gap between writing and editing is the single highest-leverage improvement you can make to your process.

The 24-Hour Rule

Do not edit your draft the same day you write it. Wait at least overnight. This is not optional — it is the most important rule in this entire checklist.

When you edit immediately after writing, you read what you meant to write, not what you actually wrote. Your brain fills in gaps, smooths over awkward phrasing, and skips right past missing context. You are too close to the material to see it clearly.

What the 24-hour gap does:

  - Breaks the mental model you built while writing
  - Lets you approach the text as a reader, not the writer
  - Surfaces structural problems you cannot see up close
  - Reveals sentences that seemed clear yesterday but are confusing today
  - Reduces emotional attachment to specific paragraphs

If you cannot wait 24 hours (deadline pressure, urgent documentation), wait at least two hours and do something completely unrelated in between. Even a short gap helps.

Change the Medium

Before you start editing, change how you are reading the text. If you wrote it on your laptop in VS Code, read it on your phone. If you wrote it in Google Docs, print it out. If you wrote it in markdown, render it to HTML and read the rendered version.

Medium changes that work:

  - Print it out and edit with a red pen
  - Send it to your tablet or phone
  - Change the font, font size, and line width
  - Read the markdown-rendered version instead of the raw source
  - Use your browser's reader mode
  - Use text-to-speech and listen to it

Changing the medium forces your brain out of "writer mode" and into "reader mode." Problems that were invisible on your 27-inch monitor become obvious on a phone screen.

Pass 1: Structure Check

The structure check is a birds-eye pass. You are not reading sentences — you are reading headings and first sentences of paragraphs. You are checking the skeleton of the document.

Structure check questions:

  [ ] Does the document start with the most important information?
  [ ] Can a reader understand the main point from the first paragraph?
  [ ] Do the headings tell a coherent story if read alone?
  [ ] Does each section have one clear purpose?
  [ ] Is the ordering logical (problem → solution, general → specific)?
  [ ] Are related ideas grouped together, not scattered?
  [ ] Does the conclusion match what the introduction promised?

The Heading Test

Read only your headings in order. They should form a logical narrative.

Good heading sequence:
  ## The Problem with Shared Database Connections
  ## How Connection Pooling Works
  ## Configuring PgBouncer
  ## Choosing Pool Size
  ## Monitoring Pool Health
  ## Common Pitfalls

  [Story: there's a problem, here's the concept, here's the tool,
   here's how to configure it, here's how to monitor it, watch out for these]

Bad heading sequence:
  ## Introduction
  ## Background
  ## Implementation
  ## Details
  ## More Details
  ## Conclusion

  [Story: none. These headings communicate nothing.]

If your headings are generic ("Introduction," "Background," "Details"), replace them with specific ones that tell the reader what each section contains.

The First-Sentence Test

Read only the first sentence of each paragraph. These sentences should carry the argument forward. If any first sentence is filler ("Let's now consider another aspect..."), rewrite it to state the paragraph's actual point.

Weak first sentence:
  "There are several things to consider when setting up logging."

Strong first sentence:
  "Structured logging — JSON instead of plain text — makes your
   logs searchable without regex."

Pass 2: Clarity Check

The clarity check focuses on whether each sentence communicates its idea as directly as possible. Read every sentence and ask: "Could someone misunderstand this?"

Clarity check questions:

  [ ] Is every pronoun's antecedent obvious? ("It" — what is "it"?)
  [ ] Are instructions specific enough to follow? (not "configure the settings appropriately")
  [ ] Are cause and effect clear? (not "this can sometimes lead to issues")
  [ ] Is every "this," "that," "these," and "those" attached to a noun?
  [ ] Are comparisons complete? (not "this approach is faster" — faster than what?)
  [ ] Are conditional statements clear about when they apply?

Dangling Pronouns

Dangling pronouns are the most common clarity problem in technical writing.

Ambiguous:
  "The service sends a request to the database. It processes the
   query and returns a result. It then caches it for future use."

  [Which "it" is the service? Which is the database?
   What exactly gets cached?]

Clear:
  "The service sends a request to the database. The database
   processes the query and returns a result set. The service
   then caches the result set for future use."

Every time you write "it," "this," "that," or "they," check whether the reader can identify exactly what you are referring to. If there is any ambiguity, replace the pronoun with the noun.

Vague Qualifiers

Remove or replace words that sound meaningful but communicate nothing.

Vague                              Specific
──────────────────────────────────────────────────
"various configurations"           "three configurations: X, Y, and Z"
"may potentially cause issues"     "causes timeout errors above 1000 RPS"
"should be relatively fast"        "completes in under 200ms"
"consider using a different approach"  "use batch inserts instead"
"a number of factors"              "latency, throughput, and memory usage"
"fairly straightforward"           [delete — if it were, you wouldn't mention it]

Pass 3: Jargon Check

Jargon is any term that your audience might not know. The question is not whether you know it — the question is whether your specific reader knows it.

Jargon check questions:

  [ ] Is every acronym defined on first use?
  [ ] Are domain-specific terms explained or linked?
  [ ] Would a developer outside your team understand every term?
  [ ] Are there simpler words that mean the same thing?
  [ ] Is jargon used consistently (same term for the same concept throughout)?

The Acronym Rule

Define every acronym the first time you use it. No exceptions for "obvious" ones — what is obvious depends entirely on the reader.

Bad:
  "The SLO for our RPC layer requires P99 latency under 50ms,
   which means the ORM queries need to hit the connection pool's
   PgBouncer instance, not the direct PG endpoint."

Better:
  "Our service-level objective (SLO) for the remote procedure call
   (RPC) layer requires 99th-percentile (P99) latency under 50ms.
   To meet this, database queries go through PgBouncer (a connection
   pooler for PostgreSQL) rather than connecting to PostgreSQL directly."

Yes, the second version is longer. It is also readable by someone who does not already know every acronym — which is the point of writing things down.

Consistent Terminology

Pick one term for each concept and use it everywhere. Do not alternate between synonyms for variety.

Inconsistent:
  "The server processes the request. The machine then validates
   the input. The node returns a response. The host logs the result."

  [server, machine, node, and host all mean the same thing here]

Consistent:
  "The server processes the request. The server then validates
   the input. The server returns a response. The server logs the result."

In prose writing, repetition is considered poor style. In technical writing, repetition is clarity. Use the same word for the same thing every time.

Pass 4: Length Check

After the first three passes, your document is structurally sound, clear, and jargon-free. Now cut its length.

Length check questions:

  [ ] Can any paragraph be deleted without losing essential information?
  [ ] Can any sentence be combined with another?
  [ ] Can any multi-word phrase be replaced with a single word?
  [ ] Are there redundant examples? (two examples that make the same point)
  [ ] Is there throat-clearing at the beginning of sections?
  [ ] Are there hedging phrases that can be removed?

Throat-Clearing

Throat-clearing is the text equivalent of "um" — filler that appears at the beginning of sections or paragraphs before you get to the point.

Throat-clearing to cut:

  "It is worth noting that..."          → [delete, just state the thing]
  "As mentioned previously..."          → [delete, or link to the section]
  "Before we dive into this topic..."   → [delete, just dive in]
  "Let's take a step back and..."       → [delete, just step back]
  "One thing to keep in mind is..."     → [delete, just state it]

Hedging

Hedging weakens your writing without adding useful nuance.

Over-hedged:
  "It might be possible that in some cases you could potentially
   see some improvement in performance."

Direct:
  "This typically improves performance by 10-20%."

Hedge only when the uncertainty is genuinely important for the reader to know. "This works on PostgreSQL 14 and later; I have not tested earlier versions" is useful hedging. "This might possibly maybe work" is not.

Pass 5: "So What?" Check

The final pass is the most important. For every section, ask: "So what? Why should the reader care?"

"So what?" check questions:

  [ ] Does every section connect to the reader's problem?
  [ ] Is the practical implication of every fact stated, not just implied?
  [ ] Would the reader know what to do with this information?
  [ ] Are there facts or explanations that exist only because you find them interesting?
  [ ] Does the document answer the question it claims to answer?

The Implication Test

Every fact should be connected to an action or a decision.

Fact without implication:
  "PostgreSQL uses MVCC for concurrency control."

Fact with implication:
  "PostgreSQL uses MVCC for concurrency control, which means
   long-running transactions can cause table bloat. Run VACUUM
   regularly on tables with frequent updates."

The reader does not just need to know things. They need to know what to do with what they know.

Common Pitfalls

  • Editing while writing. These are separate activities. Do them separately.
  • Making only one pass. One pass catches typos. Five passes catch structural, clarity, jargon, length, and relevance problems. Each pass has a different focus.
  • Editing on the same screen where you wrote. Change the medium. Your brain needs a fresh perspective.
  • Editing immediately after writing. Wait at least overnight. The gap between writing and editing is where quality comes from.
  • Keeping text because you worked hard on it. If it does not serve the reader, cut it. Your effort is irrelevant to the reader's experience.
  • Skipping the "so what?" check. A document can be clear, concise, and well-structured but still fail if it does not answer the reader's actual question.

Key Takeaways

  • Self-editing is a systematic, multi-pass process, not a single read-through.
  • Wait 24 hours between writing and editing. This is the highest-leverage improvement.
  • Change the medium before editing — print it, read on your phone, change the font.
  • Five passes: structure, clarity, jargon, length, "so what?" Each catches different problems.
  • Every pronoun should have an obvious antecedent. Every fact should connect to an action.
  • Use the same term for the same concept. Consistency is clarity in technical writing.