Tech Biz Writing

Tedious thought it may seem, the only way to master punctuation properly is to go through the elements of it one by one. The rules are not quite as onerous as most of us remember from our schooldays. In fact they’re great fun if we approach them in the right spirit of enterprise.

To command the dizzy heights of superior punctuating, only twelve elements need to be learned. Grasp these and you are in control. One hour of your time and you’ll be master of the dot in dotcom, if nothing else.

Enough of the pep talk, let’s get down to business.

Full stop
Or “point” in American. This minuscule entity ends all sentences which don’t end with a question mark or exclamation mark. The next character is usually a capital letter.

It can also be used for abbreviations: etc. or e.g.

After a quotation, the full stop goes inside the quotation marks if the whole sentence is the quote; outside the quotation marks, if the quote is only a part of the sentence.

Comma
Of all the objects in the world of punctuation, the comma is the most problematical. Placing this curiously attractive little entity in a sentence is a minefield of rules and, even worse, opinions. The old-school, rather disciplinarian approach, was to place a comma at every point where there was a natural pause for breath. Nowadays, whole texts seem to rush by with scarcely a comma to be seen. The latter solution is clearly unsatisfactory because it results in much ambiguity of meaning. The following is a fairly comprehensive guide to comma usage using the system suggested by Oxford University.

a) Between similar qualifying adjectives: “An abstemious, taciturn woman.”
But if there is no similarity, there is no comma: “A dull grey shirt.” Just think list. Abstemious and taciturn are a short list of qualities pertaining to the woman. Whereas dull and grey are different qualities; indeed a form of grey might well be described as dull. It’s clearly not a list.

b) Separating items in a list: “Books, CDs, and videos.” The comma after CDs is sometimes omitted. It’s often known as the “Oxford comma”.
Exception: “A black and white picture.” Where black and white form a recognisable phrase rather than a list. Black and white could be changed to monochrome. “Books, CDs” is not reducible because it is a list.

c) Separating co-ordinated main clauses: “Residents to the left, visitors to the right.”
Exception — when they are closely allied: “Listen to me and you might learn something.”

d) For parenthetical words/phrases: “If you do go, however, you may regret it.” Or “The man, who was not strong, soon gave up.”
Exceptions — restrictive relative clauses: “People who are short should wear high heels.”

e) Following participial or verbless clauses. “Having gone for a walk, I felt a whole lot better.” “The concert over, the audience left.”
Exception — “My daughter Mary.”

f) A separating comma is used to avoid misunderstanding: “From the houses above, the church seemed very small.” Otherwise you would read: From the houses above the church…followed by the meaningless “seemed very small.” These nuances can be very important, especially in technical writing where unclear instructions could lead to danger.
Exceptions: do not use a comma to separate a verb from an object that is a clause: “They thought, that they had it made.” is wrong, as is a comma used to separate a phrasal subject from its predicate: “A man with great strength, should always be careful of others.”

g) Use after words which introduce quoted speech: “He shouted, ‘Watch your back!’”

h) In letters following Dear Susan, Dear Sir, &c., and after Yours faithfully, etc.

But it’s not necessary following a number in an address, e.g. “10 Downing Street”; or between month and year in a date, e.g. “October 2001”.

Semicolon
A comma is the least emphatic break in a sentence. If there is a need for a more distinct break, but not sufficient for a new sentence — always a hair-line decision — a semicolon is mustered. Usually the semi will divide clauses of equal importance and similar grammatical construction, e.g. “Waking is a pleasure; sleeping on even better.” It may also be used in a sentence where commas are already employed, but where a stronger break is called for, e.g. “They approached quickly, though with some trepidation, and took stock of the situation; but decided it was none of their business.”

Colon
a) The colon connects two grammatically complete clauses where the second represents a step forward from the first, or gives further explanation, e.g. “The idea had widespread support: the merging of the two groups would improve finances.”

b) To introduce a list: one, two, three. Or after expressions, “For example”, “the following”, &c.

c) For an emphatic, formalized introduction to speech, “He emphasised: ‘Don’t do it!’”

Next: 61, Punctuation — Part 2.

Development, Line, and Content Editors
If a lot of work, or development, is needed on a manuscript, it is usually handed to the Development Editor. This may be the Senior Editor, or it may even be done by a very well-proven copyeditor side by side with the copyediting itself. These folk are also referred to as Line Editors, because they work line by line with the author, or even as Content Editors, because they are concerned with the structure of the text, which needs considerable adjustment.

As you can see, distinguishing between different types of editing is no simple matter, largely because there’s no fixed demarcation drawn between them, and different publishers have a variety of ways and means of doing them. Editors often double up on tasks, and, if someone is on leave, others may pick up the cudgel for them.

Line editing is quite a specialised activity, though, depending as it does on preserving the author’s style. Line editors often work with the author to produce the manuscript — the recent case of Joan Collins, who was taken to court by her publisher for submitting a substandard MS, and who blamed the absence of a Line Editor for the fiasco, is a good reminder of the importance of the breed.

The Commandments of Writing
These “commandments” were said to have been copied from a notice in the US Congress. Editors take note:

• Don’t use no double negative.
• Make each pronoun agree with their antecedent.
• Join clauses good, like a conjunction should.
• About them sentence fragments.
• When dangling, watch your participles.
• Verbs has to agree with their subjects.
• Just between you and I, case is important too.
• Don’t write run-on sentences they are hard to read.
• Don’t use commas, which aren’t necessary.
• Try to not ever use split infinitives.
• Its important to use your apostrophe’s correctly.
• Proofread your writing to see if you any words out.
• Correct spelling is esential.

The Production & Managing Editors
In book and magazine publishing the Managing Editor is usually just that: a manager. He/she will control much of the editing process by outsourcing work to freelancers. The Managing Editor may not even read the MSS as they come in. To get freelance work in this area, it’s usually this person you have to apply to.

The Production Editor is the first main point of contact in the production process, all content problems having been resolved by this stage. Quite often there will be either a Production Editor or a Managing Editor, the roles overlap so much. The job is almost always advertised along the lines of: “Manuscript to finished copy”. It is an in-house job and an important as well as varied one.

The Verifier or Fact Checker
Such folk spend all their time verifying facts and statements in manuscripts scheduled for press. In technical writing and editing, it’s one of the most vital areas in the production process — mistakes can be very costly in terms of time, money, and reputation. It should never be skimped

The Copyeditor
The unit on copyediting will give more precise definitions of what exactly a copyeditor does. For now we’ll give a brief outline for completion in this section.

Copyediting is, let’s face it, the lowest form of editing there is. Paradoxically, it’s also one of the most important. A poorly copyedited book, or even worse, one that hasn’t been copyedited at all, is a disgrace to the publishing industry and, I regret to say, is becoming more and more commonplace as sub-publishers rely on spellcheckers and grammar software to do the job. That these don’t work unless checked themselves is well known even to fourth formers, let alone the big-wigs of the book trade. Too often authors are expected to send in word processed copy on disk which is perfectly copyedited and proofed. Some do, many don’t.

A good copyeditor, if asked, will fill in many of the gaps that the initial process has missed. If a book is worth publishing, it’s worth copyediting. Thankfully, the best publishers still acknowledge this truism.

The Proofreader
Proofreading generally comes below copyediting in the publishing pecking order. It is, however, the final textual check before production. The proofreader is the back-stop of the process. If he misses anything, it’s too late to put right. Many a good title has been saved by an observant and intelligent proofreader who, if justice is done, will soon be entrusted with copyediting and even line editing jobs. The unit which covers proofreading, gives greater detail.

Next: 60. Punctuation — Part 1.

Technical editors are often thought of as some way beneath technical authors in the food chain. In trade publishing, however, editors, of one sort or another, occupy positions from the very top (the Commissioning Editor or Editorial Director), through the middle ranks (the Production and Managing Editors), to almost the bottom of the heap (the freelance copyeditor).

In this module we will concern ourselves with the broad sweep of the publishing editor’s perspective, but, most of all, with that of the copyeditor/proofreader, with special emphasis on the technical field, where appropriate.

The Commissioning Editor
It’s the Commissioning Editor who sets the ball rolling for the publication of a book, either by taking a manuscript from an agent — or less commonly these days, the slush pile — or by commissioning a known writer to undertake the task. This editor is now under some threat by new ideas in the publishing business.

When S.I. Newhouse took over the American publishing giant Random House, a number of sweeping changes were implemented. Editorial decisions were placed under tight constraint and usually heavily influenced by accountancy criteria. As Andre Schiffrin, an editor at the time, puts it:

“It is only in retrospect that the inevitability of this pattern emerged, though we ought to have been able to identify it at the start. While initially claiming that he would leave editorial decisions alone, Newhouse soon made changes at Random House that moved it in a far more commercial direction. Random’s profitable college [educational] department (as opposed to its weak school line) was sold off early in the game; Newhouse was so eager to get rid of it that he was willing to sell it for half of what it subsequently fetched when it was resold.”

The proceeds of this sale were used to buy another, seemingly very profitable, publisher’s list. The problem was that the accountants — not totally au fait with the book market — had got it wrong. Millions were wasted buying other properties, and selling bits of Random House. Shiffrin continues:

“Despite his early promise of editorial independence, Newhouse soon became personally involved in acquiring and commissioning titles…He arranged for huge advances to be paid to figures who clearly had very little to say in public but whose names were supposed to attract the curious masses.”

We cite the above passages to highlight the current plight of serious authors and editors within the publishing business, and the cavalier way some technical writing has been treated by the big boys of the print world. Thankfully, other specialist companies have stepped in and we are now seeing the emergence of a thriving print and electronic market in technical, especially IT, content and writing.

The Commissioning Editor, then, pursues publishable books in a variety of ways, whether through auctions with other publishers, or by in-house means. It’s the most entrepreneurial role in publishing, and if this is the route you would like to go you must be very well educated, very well connected, have a total grounding in the publishing world, a great enthusiasm for books, and be able to present a case for buying snow to Eskimos. This is not an easy job to get and very few succeed in making it to the top. Those that do often become legends in their own lifetimes — others just think they are.

The commissioning editor also helps shape the book, holding the author’s hand during the process. At this level the editor is more concerned with the structure of the project, rather than the minutiae of the text or the grammar. Here is a description of a typical Commissioning Editor by a former one:

“The Senior Editor is first and foremost a voracious reader. She [and it most often is a she] reads everything from newspapers to novels, and from encyclopaedias and dictionaries to popular magazines. She is gregarious enough to get along with authors, illustrators, designers, and other editors, and to build good relationships with agents (an agent with whom she has a good working relationship is more likely to funnel worthwhile projects and good writers her way); she is aggressive enough to go after an author she admires and to ‘sell’ a project she loves to her colleagues. She is a risk taker, creative enough to follow her instincts rather than slavishly follow trends. She is also an optimist: she believes in her books and authors and is ready to go in to bat for them. She has to be flexible, because her day, if not her life, will involve a constant juggling of responsibilities. She is well organised and detail orientated, knowing how important it is to keep a ‘paper trail’ for each project. She is practical as well as idealistic, never forgetting that publishing is a business and that books are products as well as creations of the imagination. And, like every editor worth his salt, she has a lifelong love affair with — and respect for — words.”

If you match up to that considerable template, good luck, you can’t fail! One more quote; this time from Thomas McCormack, Editorial Director of St. Martin’s Press. Here Thomas lists the qualities required for a good top-level editor: “Intelligence, sensitivity, tact, articulateness, industry, patience, accessibility, promptness, orderliness, thoroughness, a capacity to work alone, a capacity to work with others. Plus sensibility and craft. No humans need apply.”

59. Stages of Editing

A good index is essential for any technical document intended for reference. Indeed, the reference value of a technical book may be directly proportional to the quality of its index. Generally, two types of index are used:

* A general index at the back of a book — sometimes divided into names and subject indexes.
* A detailed contents list (so detailed it serves the function of an index) with subheadings — perhaps one for each chapter.

In technical handbooks, the contents list breakdown is normally employed. A list of abbreviations and a glossary are occasionally added, but a full index is often omitted completely. The reason for this is partly that the book must be updated at frequent intervals and may never be fixed into any final form. It may also be the case that few copies will be required and the standards (and costs) incurred for a commercial work would be inappropriate.

Commercial technical books of any weight or reputation include a general index, which is normally the last item in the end pages. The index is the responsibility of the writer and will either be compiled by him or placed with a professional indexer. If the book is part of a series, the depth, and hence length, of the index will be laid down by the series house style. Otherwise, an author should aim to make an index as comprehensive and comprehensible as resources of time and patience allow.

An index can only be finally completed when the book is in page proof. But much of the groundwork can be prepared in advance. In the period between sending the manuscript to the publisher and receiving the proofs, the author should go through the text, extracting the items of subjects required for the index. These can be written out on cards or slips of paper, or preferably using some indexing software. Card index, bundled in with Windows, is a useful tool in this respect, though there are more sophisticated examples.

The complexity of an index will depend on the scope of the subject, and the depth of treatment applied. It may be straightforward as in:

Convergence,111
adjustment, 113–118, 180
dynamic, 148
static, 148

Or all-embracing, as in Hugh Thomas’s Unfinished History of the World in which the index takes up 41 pages:

women, as slaves in ancient Iraq, 39; and childbearing,
52–53; use of wet nurses, 52, 53; breast and bottle
feeding, 53–4, 385; position in India, 56; home workers,
120, 121, 251; Liberation Movement, 172–3, 408–9; era of
100 per cent marriage, 232; fall in age of sexual maturity’
232n; hours of work, 255, 256…&c.

Several points may be made here: “Use of wet nurses, 52, 53;” as against, “breast and bottle feeding, 53–4.” The difference shows that the wet nurses are referred to only in passing on pages 52 and 53, whereas breast and bottle feeding constitute a substantial section over pages 53–4.

If a number of trivial inclusions occur over a sequence of pages, the device 52ff may be employed.

The reference to “fall in age of sexual maturity, 232n” indicates, by the use of n after the page number, that it is included in a footnote on that page.

If a particular topic occurs more or less continuously throughout a work, the word passim can be used instead of page numbers.

Subjects may be cross-referenced if this helps the reader: “Printing…see Lithography”. Too zealous an application of this device, however, can be tedious, if not confusing.

Next: 45. Development Documentation System.