Editing roles and goals
Let’s explore our roles and goals. Editing work takes four common forms. You may hold one of these roles, or move between them.
Standard editors
You assess layout to make sure it’s consistent, accessible, and makes key points easy to find.
You assess content to make sure it is accurate, clear, concise, and makes key points easy to understand.
You’ll check text to make sure no errors exist as it follows style guides and grammar best practices.
Editorial proofreaders
You edit your own work and the work of others.
When you work with others, you assess the same things as a standard editor, but you don’t make the changes directly.
You suggest changes for the author to consider. In the end, the author decides what changes to make.
Copyeditors
You proofread and improve design or content for a new format.
You edit the work of others to make content work for something new.
Give close attention to layout and plain language. The user experience is very important to your work.
Substantive editors
You perform full edits. You’re free and expected to suggest new approaches and major revisions. You have the final say.
Today we’ll sharpen your existing skills and introduce you to some new ideas.
What good technical writing does
Good technical writing:
- Meets users’ needs.
- Makes key points easy to find.
- Makes key points easy to understand.
- Contains no errors.
- Strikes appropriate tone.
These five jobs are always on our to-do list.
Know your users
Begin with the end in mind.
- Who uses what you write? Learn their roles, background, and expertise.
- What do they need to do? What do they need to know? What do they want to know?
- What might confuse them? Do they know the terms? Do they understand the context?
Use good design to make reading easier
- Use clear, helpful headings. Summarize the content that follows.
- Make sure headings create a logical reading order. Use styles to apply levels and maintain consistent cues.
- Use plain fonts, high contrast colors, and alt text for all images. Alt text is the short written description a screen reader speaks in place of an image.
Edit for clarity: one passage, three ways
One real passage, then two edits of it. Each edit serves a different reader.
Original text
Original No evidence suggests that point sources of NOx or agricultural emissions of VOC alone elevate ozone in the airshed. We investigated application patterns of agrochemicals containing photochemically active ingredients. Though not measured directly by T-COPS, horticultural oils could worsen ozone formation if sprayed during summer months. Alkanes used in horticultural oil application and chemically reactive light alkenes from traffic emissions may affect the airshed. We recommend measuring these ozone precursors in future studies.
Edit option 1: easy for almost everyone to understand
Edit option 1Our study found no proof that industrial pollution or farm chemical vapors alone raise ground-level ozone levels in the area. Ground-level ozone is a harmful gas near the ground that can make air harder to breathe.
We studied how farmers use chemicals that react in sunlight and may affect air quality. Some horticultural oils contain alkanes—chemical compounds that can react in sunlight to create ozone. Cars and trucks also release “light alkenes,” gases that react easily and form ozone. These sources together may increase ozone if sprayed in summer months. We recommend future area studies measure these chemicals.
Edit option 2: key points clear, assumes knowledge on the topic
Edit option 2Our study found no proof that industrial pollution or farm chemical vapors alone raise ground-level ozone levels in the airshed.
We studied how farmers use chemicals that react in sunlight and may affect air quality. These include “horticultural oils” sprayed on crops to control insects or disease. If sprayed in summer, these oils might lead to more ozone forming at ground level. We recommend future studies measure these chemicals in the air.
Measure the difference
The slides compare the original and edit option 1 in Word’s Readability Statistics dialog. Flesch Reading Ease scores run from 0 to 100—higher is easier to read. The Flesch-Kincaid grade level maps the text to a school grade.
| Measure | Original | Edit option 1 |
|---|---|---|
| Words | 73 | 129 |
| Sentences | 5 | 9 |
| Words per sentence | 14.6 | 14.3 |
| Characters per word | 6.2 | 5.0 |
| Flesch Reading Ease | 21.6 | 61.1 |
| Flesch-Kincaid grade level | 13.8 | 8.2 |
| Passive sentences | 0.0% | 0.0% |
The edit is longer in words, yet far easier to read: shorter words, defined terms, and a grade level that dropped from 13.8 to 8.2.
Meet users’ needs with info design
Inverted pyramid
Begin with the bottom line up front. Details follow.
- Frame every sentence around a single point.
- Present sequence from users’ point of view.
- Keep sentences short: under 18 words.
- Keep paragraphs under seven typed lines for print; four typed lines for content read on a screen.
Better content in five passes
We’ll apply edits to five text elements that make content complex and cluttered. Each pass is a section below.
Pass 1: Break up noun stacks and simplify words
Where to start? Shorten the stack
Start with noun stacks—long strings of nouns piled into one phrase. Editing noun stacks means shortening the stack.
Original His job involves fault analysis systems troubleshooting manual preparations.
The stacked phrase is the whole string after “involves.” Here it is as a short stack:
Short stack He prepares manuals that tell how to trace and correct faults.
Exercise: break up noun stacks
In class, you practice this pass on real sentences. Shorten the stack, then check that the meaning survived.
Shorter stacks and syllables
Two more stacks, unstacked:
- “draft laboratory animal rights protection regulations” becomes “draft regulations to protect laboratory animals.”
- “service level agreement achievement percentage” becomes “percent of service level agreement achieved.”
The slides then build one example across four steps. First the pair:
Before The successful completion of the network interface card driver installation process was verified by assigned IT personnel prior to installing the software package.
After An IT technician confirmed the network card driver worked before installing the software package.
Next, the slides underline the noun stacks in the before sentence—“the successful completion of the network interface card driver installation process was verified by assigned IT personnel”—and bold the phrase “prior to,” which the edit turns into plain “before.” Then Word’s Readability Statistics tell the story:
| Measure | Before | After |
|---|---|---|
| Words | 23 | 14 |
| Flesch Reading Ease | 17.9 | 59.6 |
| Flesch-Kincaid grade level | 16.4 | 8.4 |
| Passive sentences | 100.0% | 0.0% |
More practice: taxpayer sentences
Another before-and-after pair:
Before Verification of the taxpayer account information submission accuracy review process was conducted by designated personnel prior to the initiation of refund disbursement procedures.
After A supervisor confirmed the taxpayer’s right to resolve the unpaid tax account and approved the workflow.
A related sentence appears in three versions, each pitched at a different reader. The grade levels come from Word’s Readability Statistics.
| Version | Grade level | Fit |
|---|---|---|
| The initiation of delinquent taxpayer account resolution workflow procedures was authorized by supervisory personnel following preliminary eligibility assessment validation. | 27.2 | Too bloated and complex for any reader |
| A supervisor confirmed the taxpayer’s right to resolve the unpaid tax account and approved the workflow. | 13 | Within agency range for experienced readers |
| A supervisor approved the steps to handle the case after checking that the taxpayer could use the program. | 9.7 | For public-facing documents and forms |
Edit adverb-adjective combos
Replace an adverb-adjective pair with one precise word.
| Instead of | Write |
|---|---|
| very antagonistic | hostile |
| quite convenient | close, easy |
| extremely appreciative | grateful |
Edit prepositional phrases
Swap a stock phrase for the single word it hides.
| Instead of | Write |
|---|---|
| until such time as | until |
| in the course of | during |
| for the purpose of | to |
| in the event that | if |
| with reference to | about |
Fewer syllables = more reading ease
| Instead of | Write |
|---|---|
| optimum | best |
| motivated | driven |
| commensurate | equal |
| subsequent | next |
| consistently | in most cases |
Use modern, simple English
| Instead of | Write |
|---|---|
| modus operandi | method |
| non-sequitur | invalid |
| i.e., e.g., etc. | translate into English words |
| per annum, per diem | yearly, daily |
Exercise: simplify for users
Give them shorter stacks, fewer syllables, and concise sentences. In class, you apply all three moves to real passages. Try each one below before you open the model answer.
Exercise review
Original Our office worked with partners in the insurance industry and state agencies to provide information on wildfires’ impacts to our insurance market and the efforts in place to address those impacts.
Reveal the better version
Better We partnered with state agencies and insurance experts to explain how wildfires impact the insurance market. We also outlined the efforts in place to address those impacts.
Original An extremely thorough evaluation of patient eligibility was conducted in accordance with established procedural requirements prior to program implementation.
Reveal the better version
Better Health staff followed program rules and made sure the patient qualified before starting the program.
Original Preparation of an effective Site Improvement Plan (SIP) begins with proper identification and prioritization of emission sources to be controlled.
Reveal the better version
Better To start a Site Improvement Plan, find emission sources that require control and rank them by priority.
What did we do to simplify complex information? Answer for yourself, then compare.
Reveal what we did
- We wrote in the active voice.
- We got rid of adverb-adjective combos and used precise words instead.
- We got rid of all four-plus syllable words and used concise, clear words.
- We wrote concise sentences under 18 words.
Pass 2: Cut redundant clutter
What odds?
Read this sentence and decide: what odds does the writer mean?
“We believe that the extent of satellite military and propaganda preparations indicates that an attack on Yugoslavia in 1951 is a serious possibility.”
Do you need it? Cut redundant clutter
Each phrase below says something twice, or says more than the point needs. Ask of every word: do you need it?
- advance warning
- alter and change
- assemble together
- few in number
- basic fundamentals
- positively certain
- adequate enough
- collect together
- integral part
- contributing factor
- root cause
- midway between
- end result
- component part
- doubts and concerns
- depreciate in value
- if and when
- whether or not
Pass 3: Edit to convey action
Edit to achieve active voice
In an active sentence, the doer comes first and acts. Avoid these passive verbs: am, is, are, was, were, be, being, been.
Answer two questions to activate a sentence
- What happens? Answer it to find the verbs.
- Who or what makes it happen? Answer it to find the subjects.
Grammar refresher
- Subjects act. They are the “doers.”
- Verbs show actions. They are the “doing.”
- Objects receive actions. They are the “things.”
Show who (or what) does what
A sentence can convey action even when the subject is a thing:
Many types of residential homes and facilities provide care services to people right where they live.
Clear subjects and verbs
Before US Ecology is a disposal facility that is licensed by the state of Washington to receive commercial low-level radioactive waste.
After The state of Washington licenses US Ecology to receive commercial low-level radioactive waste.
Reveal hidden verbs
A hidden verb is an action buried inside a noun phrase. Dig it out.
Before Our team has a tendency to hold meetings on Thursdays.
After Our team tends to hold meetings on Thursdays.
Before We have made a determination that Gull Lake waters attain quality standards.
After We find that Gull Lake waters attain quality standards.
Make subjects and verbs agree
Subjects and verbs must agree in number.
Coaches give advice.
My coach gives advice.
Make pronouns and antecedents agree
Pronouns and antecedents must agree in number. An antecedent is the word a pronoun refers back to.
Watch for the wacky singular pronouns. Each of these takes a singular verb:
- anybody, somebody, nobody, everybody
- anything, something, nothing, everything
- anyone, someone, no one, everyone
- any one
Exercise: subject-verb agreement challenge
Correct subtle but critical mistakes. The sentences come to you in class.
Pass 4: Edit the details
Visuals: let purpose lead
Create visuals after you decide how you want your reader to use them.
Check the value axis on charts
The slide shows the same rising data as two bar charts, side by side, under the title “Truncated axis.”
- The left chart starts its value axis at 10, so bars from 11 to 15 look like dramatic growth. Its caption reads: “The value axis starts at ten. Liar, liar, pants on fire.”
- The right chart starts its value axis at zero, so the same values from 10 to 15 show as the modest rise they are. Its caption reads: “The value axis starts at zero. Good.”
From the speaker notes: the example comes from the article How to Spot Visualization Lies on FlowingData. The link leaves this page for an outside site.
Read figures closely
The slide shows a technical site map titled “Figure 1. Black Lake Grocery Location and Site Details.” The map marks monitoring wells, an inferred plume boundary, roads, a pond, a retaining wall, and the Black Lake shoreline, with a legend. Two details are circled for attention:
- A note beside the north arrow: “Map based on Envirosolutions (2004). Figure. Not drawn to scale.”
- The legend’s scale bar, labeled “Scale in feet (approximate),” with the footnote “Sample locations are approximate.”
Details like these change what a reader can safely conclude from a figure. An editor checks them.
Keep numbers and units together
Train yourself to insert a nonbreaking space between numbers and units, as in 2.0 µL/L. A nonbreaking space keeps the number and its unit on the same line.
In Word: on the Insert tab, select Symbol, then More Symbols, then the Special Characters tab. Select Nonbreaking Space, then Insert. The shortcut is Ctrl+Shift+Space.
| Character | Shortcut key |
|---|---|
| Em dash (—) | Alt+Ctrl+Num - |
| En dash (–) | Ctrl+Num - |
| Nonbreaking hyphen | Ctrl+Shift+_ |
| Nonbreaking space | Ctrl+Shift+Space |
Pass 5: Strengthen layout and design
Set limits that help readers
- Sentences: 12–17 words, max.
- Paragraphs: seven typed lines for print; four typed lines for screen.
- Group related ideas under headings and headlines.
Use headings and headlines
Use styles to apply levels to all headings and ensure consistent cues.
The slides show a free-standing headline from a public web page. The headline “Get involved” stands above this paragraph:
You can shape environmental decisions that impact your community. We offer a variety of ways for you to get involved. Click on our calendar of events for a schedule of upcoming public comment periods, hearings, meetings, workshops, and open houses in your community. Your thoughts, ideas and comments are most welcome. You can also find links on how to report a spill. Get household tips for cleaner land, air, and water. Find information on recycling. Explore volunteer opportunities. And much more.
A second example is a “Beekeepers tax guide” web page marked up to show which style carries each element:
| Element on the page | Style applied |
|---|---|
| “Beekeepers tax guide” (the page title) | Heading level 1: title |
| “Contents” | Heading level 2: all major subsections |
| “Beekeepers tax guide” (the contents entry) | Heading level 2: all major subsections |
| The linked topics (Definitions; Business and occupation tax; Sales tax exemptions; Questions and answers; Taxation of other beekeepers) | List item style creates the list |
Keep learning
Do you need to learn more about universal design and document accessibility?
Join us for Accessible Document Design for Beginners. An approachable, simple workshop on the basics. Course number: 01-03-EW68.
Great work—share your feedback
Please share your thoughts. Open your course evaluation link in the chat, or from the Learning Center home page go to: SELF > Learning > Learning Activity Evaluations.