Technical Writing – How to Edit a Technical Document?
Imagine you’re a technical writer looking over my shoulder as I’m editing a technical manual.
This is how I’d do it:
ORIGINAL: “Logging in involves the Operator typing in his User ID and Password.”
BETTER: “To log in, the Operator must enter a valid User ID and Password.”
ORIGINAL: “The operator’s assigned authorities for operating, configuring and maintaining the system control the degree of operator authority.”
BETTER: “The range of the operator’s freedom to operate, configure and maintain the system defines the level of his or her authority.”
ORIGINAL: “This button allows the user…”
BETTER: “This button enables the user…”
(WHY: Allowing denotes a power relationship between two parties. A system does not have the power over a user that two individuals might have over one another. Thus, I always prefer the verb “enable” which reflects a purely technical capability.)
ORIGINAL: “There are no configurable aspects in this table and it is used to simply display the current device configuration settings.”
BETTER: “The user cannot edit the contents of this read-only table that displays the current device configuration settings.”
(TIPS: Watch out for filler words like “simply” or “aspect” and eliminate them. Whenever possible, switch from passive to active voice.)
ORIGINAL: “The meter measures a voltage lying within an overlapping region of two state’s voltage windows.”
BETTER: “The meter measures a voltage between the minimum and maximum values in the region where the two states’ voltage ranges overlap.”
(Good editing usually ends up with shorter sentences. But once in a while it requires a longer sentence to clarify a complicated piece of information, as is the case here.)
ORIGINAL: “Password — This is a phrase of letters up to 10 characters long.”
BETTER: “Password — 10 characters, maximum.”
ORIGINAL: “As compared to the permanent magnet speakers, standard headphones are considered to be high-impedance devices.”
BETTER: “Standard headphones have a higher-impedance than the permanent magnet speakers.”
IN SUM: Editing is cleaning up. I love things that are clean and work well. Don’t you?
