Tech Biz Writing

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.

The New Oxford Dictionary of English defines an abstract as “mak[ing] a written summary or statement of (an article or book): staff who index and abstract material for an online database … a summary or statement of the contents of a book, article, or formal speech: an abstract of her speech.”

To abridge is similar: “shorten (a book, film, speech, or other text) without losing the sense.” Abridgement is “a shortened version of a larger work.”

Abridging is usually used for larger works, especially literary; abstracting is more often used for scientific, technical, or legal articles. The process is usually the same, however, and clients will often use the two words synonymously. The essential difference is that an appended summary of a report, or book, will be an abstract, while a shortening of the whole book from say 50,000 to 20,000 words is an abridgement.

Technical writers may occasionally be asked to do this, but it’s not a usual task for the general practitioner. This is very much a specialised job, given to those with a particular skill for extracting the nub of the matter, and reducing a whole lot of words to a concise and meaningful few. If you have a penchant for this type of work you are advised to consult a number of technical treatises on the subject, usually found in manuals of librarianship or database studies.

Next: 44. Indexing.

Technical illustrations need to be checked in much the same way as the accompanying text. In complex drawings, authors should watch particularly for omissions of lines or annotations. Annotations may be direct or indirect. That is, set on the drawing, or keyed to a separate table. In the latter case all cross-referencing should be confirmed.

The following checklist suggests points to look for when vetting a technical illustration:

* Has the specification been adhered to?
* Is the format correct?
* Are there any technical inaccuracies?
* Is the titling correctly placed and worded properly?
* If the illustration is to be reduced, is the lettering readable?
* Is the page identity or figure number accurate?
* Is the security marking present and correct?
* Is the layout and composition clear?
* Is the line thickness to spec and uniform?
* Are cross-references correct, or hyperlinks live and true?
* For double-page spreads, is the material across the fold readable?
* For simulated shadow-lines, are these placed correctly and uniformly?
* If a variety of tints are used, have they been correctly indexed?

For more detail in this peripheral area for the author, there are many good books available.

Next: 41. Materials and Equipment.

Proofreading is done by the author (and others) on special sheets provided by the printer. “Proofs” are example pages taken from the printing medium, as set or photographed, and fall generally into three kinds:

* Galley proofs
* Page proofs
* Machine proofs

The first two categories of proof are representative of the textual arrangement of the type, but not of the final print finish. The machine proof, on the other hand, approximates the condition of the printed book in areas of quality.

Galleys are taken at an early point in the typesetting procedure, and do not indicate the eventual configuration of the pages in the book. Traditionally, the compositor would set the type in a clamped frame called a galley. The printed sheets derived from this would be sent to the writer for proofreading; the principal aim being to reduce the number of changes needed later on in the process when amendments are much more costly.

The page proofs, indicating actual book pages, are taken when the lengths of run-on text are composed into the correct page size. Pagination and other page references can now be incorporated into the text, and the index put into its final shape. Modern books, printed by lithographic techniques, are often proofread only at this stage. For a more comprehensive consideration of proofreading, plus tables of proofing symbols, see the later discussion.

To gain an impression of the finished print quality, a machine proof must be requested from the printer. The reason for this is that page proofs are usually taken on a small printing press specially set aside for the purpose. By its nature it lacks the sophisticated facilities of the more elaborate production machines, and doesn’t therefore produce anything like the eventual print finish that may be expected. A machine proof is one that is taken from the actual production press and, while it gives a high quality sample, it’s an expensive operation, since the machine is temporarily taken out of its high productivity role.

On the question of the costs involved at the proofing stage, authors should know that there is a limit to the number and extent of changes they can make in this area. Generally, printers acknowledge two types of correction:

* Compositor’s errors
* Author’s corrections

The first are redressed free of charge to the author and his contractor. Author’s correction, however, are usually limited to a figure around 10% of the cost of typesetting. Printers expect, and with some justification, that most problems of grammar, spelling or content will have been filtered out by this stage.

A margin is allowed of course, but it should be borne in mind that 10% of costs does not mean 10% of the text can be amended. The actual figure is disproportionately smaller that this, and any over-run is charged to the writer’s or publisher’s account. Indeed. the margin is so tight that there is, for practical purposes, scarcely any room for rewriting the text at this point. An inexperienced writer would do well to cultivate a measure of self-discipline in these matters.

Next: 35. Printing.