Technical writing is always defined with the attributes of crisp, clear, concise instructions that are technically and functionally accurate. While technical writers use research, comprehension, and outlining to eventually document complex thoughts and actions into user-friendly content, it is the technical editors’ responsibility to ensure that this content is not complex to read. Fulfilling such a responsibility requires special technical editing skills.
The technical editor is usually the first critical user of a technical draft and starts by finding whether:
- The needed information is available.
- The available information is understandable.
- The information can help to perform an action or meet a user need.
From the editing perspective, technical editors stress on the following writing techniques to ensure that the above three targets are met:
Logical organization of content: Topic and paragraph based content structure, step-by-step instructions, lists and tabular formats are mostly used in technical documents. Headings can be intelligently used to distribute content over a section or chapter. The editor ensures that the content is relevant for a topic and the paragraphs are interconnected. Steps should provide sequential access to information and enable the user to correctly perform a procedure or action. Tables should be aesthetic and provide easy-to-find information.
Use of short and simple sentence construction: Wikipedia says – “There is no absolute limit on the length of a written English sentence. A sentence can be made as long as time allows with concatenating (linking) clauses using grammatical conjunctions, such as and. Sentences can also be extended indefinitely by the addition of modifiers and modifier clauses, …” Fiction-writing has seen many experiments with the longest possible single sentence but newspaper, scientific, or technical editors expect the smallest possible sentence to convey a single thought, fact, or user action. A short, simple sentence grabs and holds a reader’s attention, and is easy to remember. A simple sentence must contain information that the mind can easily process and the user can immediately use.
Omission of redundant and difficult words: The technical editor looks at the document from the average readers’ perspective—chopping out the jargon, simplifying the too-technical material, rewriting the still-complex-to-read-and-understand thought, and eliminating redundant words, foreign phrases, and verbosity. If one word can convey the same meaning, there is no need for two.
Use of Active voice: This is almost every technical editor’s pet peeve. A technical editor will attack passive sentences with a vengeance and want them to be replaced with active sentence construction. Active voice sentences are usually simple, direct and in the simple present tense. A tip for active voice constructions is to use the word “you” and other pronouns in a sentence.
Use of illustrations, lists and tables: A picture speaks a thousand words! Whenever, appropriate, the technical editor may suggest using tables or graphically representing information to save on the written word. Technical editors will look for information that can be put into a bullet or numbered lists, and will always check for parallel sentence construction in lists.
Usage of punctuation: Punctuation is not just the comma, semi-colon, and period. It is the science and art of using spaces, typographical elements, and signs that eventually make a sentence meaningful, and correct in both reading to one self or when speaking aloud. Technical editors will look for the usage of proper punctuation and will ensure that long sentences with colons, semi-colons, or dashes are replaced with smaller, complete sentences. Sentences and paragraphs where a lot of commas occur are good contenders for being transformed into lists or tables. Hyphens, dashes, and em dashes should be used appropriately.
In conclusion, as writers and editors we all know that filtering technical concepts into simple explanations is challenging. However, every technical editor will have acquired this valuable skill and will encourage technical writers to work on attaining this trait that usually comes with a lot of practice. So, take up the challenge to write simple.
Trivia: The Plain Writing Act of 2010 was signed by President Obama on October 13, 2010. The law requires that federal agencies use “clear Government communication that the public can understand and use.” On January 18, 2011, a new Executive Order was issued that states that “[our regulatory system] must ensure that regulations are accessible, consistent, written in plain language, and easy to understand.” In the U.S. Plain language is the law!
About the Author
Aneesha Myles Shewani is a technical editor, working primarily on application user manuals and end-user training material. She is currently employed with Fiserv and has expertise in establishing style guides and editorial standards for print, online and mobile media. She spends her leisure time in reading and writing about a variety of topics, ranging from history to science fiction. Aneesha also writes fiction and some of her work can be read on her blog: http://felinemusings.com/.