Tech Biz Writing

If the MS is a book to be published commercially, the typescript submitted will not be camera copy, as the publisher will handle all the typesetting in-house. However, this doesn’t remove the writer’s responsibility to provide the publisher with a suitably prepared copy.

All publishers have a house style. Some go so far as to distribute printed booklets to authors setting this out in detail. In the age of the word processor it means that the compositor stage can be side-stepped, and even copyeditors are rarer than they were. Computer programs can do a lot — though not everything — and each stage missed out, means a significant saving in costs. If an author is writing a commissioned book, or even if it’s intended for a specific publisher, effort should be made to conform as much as possible.

In the absence of a style guide, however, a similar volume from the same imprint will provide some information on these matters.

It’s vital that the pages are typed to a standard pattern: double-spacing between lines and consistent margins. This is to allow the MS to be “cast-off”, or the number of words estimated, and changes to be made. If it’s word processed, of course, this will all be done by the computer software. Illustrations should be packed in a separate envelope or box and carefully annotated so that reference can be made to the manuscript sheet where each belongs. Figure numbers should also be clearly marked in the margins of the MS at the appropriate place, and a list of illustrations supplied to tie the whole thing together.

The final icing on the cake, so to speak, is the prelims and end pages. These may include the following:

Prelims
* Half-title page: exhibits only the title of the book.
* Half-title verso: may carry the author’s previous works or companion titles.
* Title page: title, subtitle, author, publisher and other relevant material.
* Title verso: the history page, copyright and ISBN, printer information, and dedication. Eventually, the book’s publishing history will appear here.
* Preface: a short piece usually explaining why, how the book was written.
* Contents: chapter headings and page numbers. May contain subheadings.
* Illustrations: often varies in scope, but self-explanatory.

End pages
* Conclusions/Postscript: summary of main message; predictions of future.
* Glossary: dictionary of terms used.
* Notes/References: if no footnotes, they are all gathered here.
* Appendixes/Annexes: additional detailed material; expansion of text.
* Bibliography: list of relevant publications for reference or further study.
* Index: vital in a book intended for reference

This the point where the MS leaves the author for good, only to be returned in book form. It‘s the final moment of truth.

Next: 33.Camera Copy.

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.

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:

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 is not an easy area for technical writers who convey facts above all. Those who write commercially, in magazines, for example, need to have a larger vocabulary and a better sense of “style” than those who write simple handbooks.

The hallmarks of a good style are:

* Clarity
* Cadence, or balance
* Appropriateness
* Brevity

The enemies of bad style are many, but include:

* Jargon
* Cliché
* Inappropriate ornament
* Somnambulism (putting the reader to sleep).

Style is something you develop as you get used to using the language in an expressive and lucid way. Technical writers should not ignore it. It make you a “real” writer!

We recommend you read the units on Business Writing for this course. Links at the top of the sidebar.

Next: 29. Technical Vetting.

You will now need to prepare a work schedule to estimate the time likely to be needed for each step in the process. The main variable will be the number of times an author will have to go through each loop. Experience should give some indication here, but if not, it is certainly a wise practice to build in a contingency for perhaps two or even three trips around the course. An alternative would be to set a limit to this procedure, in agreement with the client, ensuring that some sort of draft is produced to time.

A straightforward time-based chart may then be constructed. For large-scale projects involving a number of volumes, the Project Evaluation and Review Technique (PERT), or the Critical Path Method (CPM) may be used. There is a lot of good software available now in this field. Approach a good supplier or, as usual, write to the Microsoft Campus in Reading. A general discussion of network analysis as these methods are called is given elsewhere under: Additional Subject Matter.

Next: 26. Costing.