Tech Biz Writing

Manuals
Level of readership: Technical manuals are produced for the skill level of the reader/user. There are at least three levels for maintenance handbooks:

* Simple maintenance
* Technical maintenance
* Workshop technical maintenance.

Customer support documentation: All literature written with the aim of providing a customer with accurate, up-to-date information about a particular product.
Specification: Detailed description of a product. A document prepared by an authority as a basis for the production of a technical manual.
BS4884: British Standard specification for technical manuals. Uses a nine-category system of book organisation.
Synopsis: A document, varying in detail, providing a summary of the contents of a book or document. Typically it contains chapter headings, subheadings and subject breakdown. It may also include a page count and/or an estimate of the number of paragraphs. A list of illustrations is usually provided. Useful for costing and organisation of material.
Vetting: A technical check on draft material.

Reports
Product documentation: Literature which provides information on a product and its progress.
Purposes of a report: To give an account of a subject. To arrive at a basis for discussion. To reach a conclusion. To plan further action. To make recommendations. To disseminate data. To provide a record or reference.
Subject-orientated report: Divided into topics or subject groups.
Chronological report: “Real-time” record of events or progress.
Conceptual report: Abstract or philosophical aspects of a subject.
Main features of a report: Title, contents, aim, summary, body of document, conclusions, index.

Technical articles
Article: Compact piece with a central point or theme.
Angle: Journalistic term relating to the orientation of an article in terms of its subject matter.
An article requires: Organisation — construction allowing the reader maximum access to the subject; and Readability — quality of a piece of writing that maintains a reader’s interest throughout.

Technical sales literature
Glossy: A brochure produced on high-quality paper with coloured illustrations, and which attempts to maximise the sales of a product or service.
Motif: A theme or recurring logo linking the pages of a book.
Visuals: “Roughs” or visuals are a dummy copy of a brochure sketched out by a graphic artist.

Technical training material
Programmed learning package: A collection of aids, usually “mixed-media”, structured for layer-type or reinforcement learning. The aim is to administer a measured quantity of information in fixed units of time.
Reinforcement learning: A spin-off of Pavlov’s classic conditioning experiment on dogs, but this time aimed at humans. Reinforcement is achieved by ingenious repeating techniques, using data which may be subtly veiled to make it more palatable to a modern audience.

Software documentation
Software: Anything in a computer system not definable as hardware: the programs, operating system, compilers, utilities and documentation.
Program maintenance: The act of patching or fixing a program when a bug is found. In practice, there is no way of testing every loop and procedure in a long, complex program. Consequently, errors may be constantly discovered in even the most mature software. The documentalist annotates programs in such a way as to provide maximum assistance for subsequent maintainers.
Stages of software development: As any other technical product: requirement, specification, system design, software system design, program design, implementation, integration, acceptance testing, maintenance &c.

Next: 52. Outline and Design

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.

The translation of technical material presents both writer and linguist with special problems. There is no such thing as a perfect translation. Several translators, given identical texts, will produce different solutions to the puzzle. There is, though, a middle way through the complexity, balancing accuracy of fact (essential in a technical document) with interpretative freedom. The exact end-product will, of course, depend on the requirements of the particular job. Generally, there are three types of translation:

* A literal translation rendering the original clause by clause.
* A free translation giving the translator wider scope for adaptation into the vernacular.
* A partial translation in which a summary is made of the original text.

A snappy sales brochure, for example, requires above all else a true colloquial rendering for the target community. Either the translator must be a competent copywriter with the freedom to adapt the material to local requirements, or the verbatim translation should be given to a copywriter in the target country for further work.

At the other extreme, a description of a maintenance procedures for an intricate piece of equipment with stringent safety precautions, would call for a strictly formal translation, in which each sentence is rendered literally into the new language.

Writers producing texts for which translations will be necessary, should bear certain points in mind. A badly edited or poorly punctuated document will cause problems in the original let alone in translation. Writers should always ensure that their meaning is clear and unambiguous, avoiding inconsistent terminology, the use of colloquialisms, and any other loose deviations from a tight and accurate text which a translator will need to do a good job.

Choosing the right translator is an important consideration from the outset. Starting on the premise that practitioners work best when translating into their own native tongue, two other points immediately arise: their understanding of the source language, and their technical competence to handle the subject matter. Both aspects will be crucial to the quality of the finished product.

If it falls to the author to do this, how to engage a suitable translator? Fortunately the possibilities are wide:

* Local contacts — agencies, foreign wives or husbands of friends &c.
* Directories, Yellow Pages, the Internet, for listings of bureaux or translators.
* The British Standards Institution (BSI) has a translation advisory service.
* Embassies, High Commissions, Consulates may keep lists of their nationals who offer a translating service.

Translating is a well-paid occupation — or so it seems from an author’s viewpoint. The price of translation is usually quoted as a rate per thousand words or, for small jobs, a unit called a folio, 75 words, is used, and is the least that will be charged for. The main factors likely to put up the cost of any translation are, the language to be used (i.e. non-Roman scripts like Arabic, Japanese or Russian will be significantly more expensive), and any special requirements such as side-by-side translations or additional copywriting skills. Cost assessment will be based on:

* Time factors.
* Technical content.
* Specialised subject matter.
* Specifications or standards to be observed.
* Language — European/non-European/non-Roman script.
* Any proofreading or other tasks involved.

English is now the major world language in terms of international communication. In areas of science and technology this dominance is even more pronounced. The Internet has only increased the change from lingua franca to lingua britannia, or more specifically, lingua america. Over the years this has tended to give the British a false sense of security. An insular mentality has prevented any great leaps forward, but one way of counteracting it is to make sure that all technical and customer support documentation receives the best possible translation into the language of the target population. Efficient communication overcomes many other deficiencies.

Next: 43. Abstracting and Abridging.