Tech Biz Writing

DDS is a documentation/methodology employed in system design. It can be used for both electrical and mechanical engineering disciplines, covering hardware, software, logic and functional dimensions. It has become a versatile tool for designers of any system, allowing detailed recording of progress as the project develops. It’s not a publications application, but more a methodology and information system for development purposes. Writers, however, may be involved in its implementation, and will refer to it during the writing of other project documentation. It is a good example of documentation and information organization systems, which is how we are using in here.

The Development Documentation System was begun in the Sixties by the Naval Applied Science Laboratory in America. Since then much work has been done on it in the UK, and it has been used effectively for some naval and military projects. A full account of the procedure can be found in the MoD’s Naval Weapons Specifications.

DDS uses a hierarchical approach to the recording of design information. The levels move from the general to the detailed: from the highest and broadest level (showing the system itself) through as many intermediate levels as are considered necessary, to the lowest (illustrating the smallest detail). The format used will depend on the engineering discipline involved, and whether the subject matter is software, hardware, function or logic orientated. Advantages of DDS include:

* Ease of update.
* Results of studies or analysis may be incorporated.
* Evolves with the project, allowing a dynamic approach to documentation.
* Provides a complete record of the design stages.
* Enables a testing philosophy to be formulated at an early phase of development.
* Allows a wide choice of record formats.
* Co-ordinates all design information without necessarily replacing standard publications’ procedures.
* Presents maximum information in minimum time.
* Excellent for monitoring progress.
* Encourages a systems approach to design which smoothes over any interface
problems.

DDS is an example of a systems approach to technical documentation which authors may not come across often unless working on military projects. Newer technology methods have developed and extended it to match the complexity of modern engineering design. But if a technical writer gets involved in a very large project, such as the development of an aircraft, he/she will be plunged into a documentation implementation arrangement very similar to DDS.

Next: 46. Diagnostic and Maintenance Documentation

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.