Editing Sample

Editing for Clarity

Much of technical writing is editing: turning a rough draft, a developer's note, or a vague message into something a reader can actually use. Each example below shows a realistic before, a revised after, and the reasoning behind the change.

This is a technical writing sample. The "before" passages are representative of unclear source material a writer is often handed; the edits demonstrate concision, plain language, and structure. It is not tied to any real document.

1. Lead with the point, cut the filler

Before

It should be noted that in the event that a schedule is not provided at the time that a report is created, generation of the report will only be performed at such time as a request is made by the user, and the report will not be generated in an automatic fashion.

After

If you do not set a schedule, the report is generated only when you request it, never automatically.

What changed
  • Cut the passage from 52 words to 16 without losing any meaning.
  • Led with the condition the reader cares about ("If you do not set a schedule").
  • Removed empty openers: "It should be noted that," "in the event that," "at such time as."
  • Replaced passive voice ("generation will be performed") with active voice ("the report is generated").
  • Addressed the reader directly as "you" instead of "the user."

2. Say what went wrong, and what to do

Before

Error: The request could not be fulfilled owing to a failure in the validation of the authorization token, which was determined to be either non-present or otherwise non-conformant with the expected credential format in the request header.

After

Error 401: Your API key is missing or invalid. Add a valid key to the Authorization header and try again.

What changed
  • Named the real problem in plain words: the API key is missing or invalid.
  • Told the reader what to do next. The original described the failure but never offered a fix.
  • Added the status code (401) so the error is specific and easy to search.
  • Cut the jargon: "non-conformant with the expected credential format" says nothing a reader can act on.

3. Break a wall of text into a checklist

Before

Before you deploy you need to make sure the build has passed CI and that staging tests are green and you should also check that there is not an active incident and confirm there is no change freeze and you need to have recorded the current version so you can roll back and then post a notice in the team channel.

After

Complete these checks before you deploy:

  • The build has passed CI and staging tests.
  • No active incident or change freeze is in effect.
  • The current version is recorded for rollback.
  • A start notice is posted to the team channel.
What changed
  • Split a single 58-word sentence into a scannable checklist a reader can work through.
  • Gave every item the same grammatical shape so the list reads cleanly.
  • Removed the chain of "and ... and ... and" that hid where one step ended and the next began.
  • Added a short lead-in line so the list has context on its own.

What I look for when editing