Tech Biz Writing

Editing is the subject of a later module in this course, but it is appropriate to cover some ground here, not only because it falls into place at this stage, but because there are certain editing tasks which are the preserve of an author.

In technical writing an editor is concerned with three aspects of a draft:

* Does it conform to spec, and house style?
* Is the flow of material logical?
* Is the grammar and punctuation correct?

Editing is a vital function in the preparation of any document. It is particularly applicable to technical literature because of the need for accuracy and precision. A reader can be misled by badly worded sentences just as surely as by technical inaccuracies in the text.

Normally, a first draft will be submitted for editing once the technical changes arising from validation have been incorporated into the manuscript. It is advisable to present a word processed draft to the editor, since any document reads better than in pencil draft. Changes though, should be marked up on the MS (manuscript) rather than entered on the computer — the editor may not be as technically qualified as the author, who needs to approve the changes before they are set in stone.

The editor may be a colleague in the author’s own office, or he/she may be a specially appointed staff member in the client’s company. Frequently, the person in charge of the project will perform the editing function. He will be working on the widely-held, but false, assumption that anyone can be an editor. In this situation, the writer would do well to have his work checked by a fellow author before submission.

It’s important, therefore, that all authors are aware of the fundamental principles of editing; not only that they may improve their own work, but in case they are called on to edit another’s.

What then does an editor do? Here is a simple checklist of points to watch for in the editing of any draft MS:

* Conformity to specification headings.
* Page numbering.
* Paragraph numbering, if applicable.
* Conformity of contents list to text.
* Layout of illustrations as per spec.
* Unusual words, or phrases.
* Unexplained abbreviations.
* Long words that may not be understood.
* Unnecessary words — adjectives, adverbs, especially.
* Undefined technical terms.
* Balance of text: length of paragraphs &c.
* Ambiguities in flow of text.
* Punctuation.
* Grammatical construction.
* Spelling.
* Conformity of meaning of text to what was intended.

Editing is not an easy job. It can be tedious, and as is apparent from the checklist, requires many literary skills, as well as some familiarity with the technical background of the subject matter. This is illustrated in the following example of typical editorial decisions:

“The Large Local Exchange, like all Local Exchanges, utilizes subsystems specially conceived for large local exchanges (LLEs).”

Suggested amendment
As with all local exchanges, the large version (LLE) makes use of subsystems specially designed for them.

The sentence could be misleading. It implies that all local exchanges, regardless of size, use subsystems designed for Large Local Exchanges. Of course, this may very well be correct, especially if the LLEs were designed first, but it seems unlikely. The probable ambiguity can be side-stepped by adopting the second approach. In the absence of hard information, this is an editor’s way of avoiding a possible logical error, while covering himself against an outside chance that the facts as stated may be correct. Engineers sometimes go to huge lengths to state every possibility in a written draft, so that it reads like the outpourings of a demented lawyer being paid by the word. A good editor has to make it readable, while not interfering in the total accuracy.

Oh, and the capitalization is a bit plodding too.

Stylistically, the sentence is a tautology and it reads badly. It uses the words “local exchange” three times in sixteen words. A question of house style also emerges in that “local exchange” first begins upper-lower case, descends to lower case, then rises again to initial capitals. Obviously a consistent choice must be made, and this is usually an editorial decision. I say, usually, because in certain cases there is an industry-wide usage, perhaps derived from regulatory documents or similar. The editor should be aware of all these nuances.

“The equipment will happily run on either 240V or 110V.”

Suggested amendment
The equipment may be run on 110 or 240V.

Inanimate objects should not be anthropomorphized. Machines can’t be happy.

Transmission equipment
LINE CIRCUITS

Suggested amendment
In the absence of a definite spec ruling on heading weights, attention should be given to the logic of any heading scheme used. Reversing the above weights would be more appropriate:

TRANSMISSION EQUIPMENT
Line circuits

Good editing comes with practice. Experience is an essential element in the art. But with an adequate mastery of English and a reasonable technical background, there is no reason why an author should not also be a useful technical editor.

Next: 31 Final Draft.

This entry was posted on Sunday, June 18th, 2006 at 10:07 am and is filed under Technical Writing, Business Writing, Publishing, Documentation, Design, Research, Technical Vetting. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.