T.S. Eliot dedicated the “The Waste Land,” arguably one of the most important poems written in the 20th century, to Ezra Pound for his timely edits. According to Richard Ellman, Pound persuaded Eliot to remove several poems that Eliot had inserted between the stanzas of “The Waste Land.” As Pound said, “the longest poem in the English langwidge [sic]. Don’t try to bust all records by prolonging it three pages further.” (From “The First Waste Land.” In Eliot in His Time: Essays on the Occasion of the Fiftieth Anniversary of The Waste Land.” Princeton, Princeton UP, 1973.)
So what has any of this to do with editing a technical manual?
First and foremost, concision and clarity (which often go hand in hand) are the primary duties of every editor – technical or otherwise. Verbosity makes cloudy what should be clear because it distracts the reader from the point the writer is trying to make. Unless the writer is purposely trying to confuse the reader – in a novel, for example, to make the narrator’s perception of reality or point of view suspect – each word in a sentence must contribute to the meaning. In technical communication, this is the first rule: “every word must contribute meaning to the sentence. Technical writing is information delivery.” (http://en.wikiversity.org/wiki/Technical_writing_style).
The editor must verify that the writing is grammatically correct. The tools we use to write technical manuals have improved dramatically over the years and have helped correct many a grammatical or spelling mistake. But the tools are not perfect and we have to rely on the editor to highlight the mistakes the tools may miss: dangling modifiers, the correct “there,” “their,” or “they’re,” and the difference between “its” and “it’s.”
But the technical editor has another – perhaps, more important role in editing a document – verify the accuracy of the instructions to make sure the instructions the writer is communicating are clear and correct. What’s the point of publishing a manual if the step-by-step instructions are wrong?
Let’s look at a couple of examples.
At Shoap Technical Services, we work extensively in the payments industry. In the 25 + years we’ve been documenting products used in payments, we have learned much about the intricacies of the complicated and sometimes bizarre world of payments. If a novice writer, therefore, incorrectly describes voiding a credit card transaction (which is simply canceling it; the transaction does not appear on the cardholder’s statement) as a return (which results in a credit to the cardholder’s account), it is easy for the editor – without consulting (or bothering) a Subject Matter Expert (SME) – to correct the mistake.
Or, as has happened recently, a writer was confused about some arcane PCI-DSS compliance rule and incorrectly included a statement in a document that was blatantly false. The editor, conversant with PCI-DSS, pointed out the error and the writer was able to correct his mistake. Again, without relying on the SME to notice the problem.
Of course, technical writers depend on SMEs to review and verify the accuracy of their work. But our experience shows that SMEs rarely have time or desire to read what we write – they’re too busy “fighting fires” – so instead, we rely on a knowledgeable editor to make sure that the document is correct.