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

Fritjof Capra, in his book The Tao of Physics, explains the task of a technical writer as follows: “The notion that all scientific models and theories are approximate and that their verbal interpretations always suffer from the inaccuracy of our language was already commonly accepted by scientists at the beginning of th 20th century, when a new and completely unexpected development took place. The study of the world of atoms forced physicists to realise that our common language is not only inaccurate, but totally inadequate to describe the atomic and sub-atomic reality. Quantum theory and relativity theory, the two bases of modern physics, have made it clear that this reality transcends classical logic and that we cannot talk about it in ordinary language.”

That this theoretical sophistication will eventually filter through to the down-to-earth concepts of engineering is certain, and has probably happened already. As science continually reassesses itself in terms of its wider implications, engineering too will need to adapt to the new complexities and possibilities. Language will be forced to expand and develop in an attempt to remain abreast of the new philosophies. Even simple technical descriptions, essential for complete understanding, will need to reflect the depth of theoretical complexity inherent in modern devices.

Technical writers of the near future will be resourceful individuals. They will need to span disciplines even more than they do now. But while techniques move on, and change is there to be described, they will survive. And, with a bit of luck, prosper.

Next: 51. Reinforcements - The Field.

Until recently, British copyright lasted for fifty years beyond the author’s death. Now, this has been extended by the EU to seventy years. There is support too for efforts to secure a decent return from those who would readily exploit an author’s work without paying for it. Photocopying used to be a licence to save money. Hardly anyone thought twice before reproducing articles, chapters from books or even a whole book without reference to the copyright holder.

There are now agreements with education and commerce on a licensing scheme for reprographic rights. Whether or not a similar scheme can be applied to electronic rights depends largely on developing an effective policing policy. Reports are already filtering through the technological grapevine of new metering systems which will allow publishers to monitor and record the use of their information on the Internet and other networks. In early 1997, the World Intellectual Property Organisation, the UN’s agency responsible for administering copyright conventions, required member states to outlaw devices aimed at bypassing technical measures to prevent unauthorised copying.

Meanwhile, there is much that the individual writer can do to guard against the free use of what is, or what might turn out to be, a valuable property. The starting point is the small print of the contract.

One unnecessary fuss over copyright, centred on a scheme launched by Simon & Schuster, followed by Macmillan and Wiley, “to keep works of academic value in print on a permanent basis” by printing on demand. (Modern digital printing techniques allow works to be stored on disk, updated frequently, and printed off “just in time” to the customer’s order). The drawback, from an author’s point of view, is that while under current rules if a book goes out of print for more than eight weeks the copyright in the text reverts to the author, this print-on-demand initiative could be used by a publisher to hold onto these rights. The issue will doubtless be decided eventually by combat between expensive lawyers. Meanwhile, we can only wonder at the further confusion over who owns what created by the new technology. In the Far East it is reckoned that over 90% of all videocassettes sold are pirated. Unauthorized printing of books in China, Russia and a motley of smaller nations is said to be depriving British publishers and their authors of £200m a year. As for the photocopier, it’s now responsible for some 300 billion pages of illegally reproduced material.In most books a copyright notice appears on one of the front pages. In its simplest form this is the symbol © followed by the name of the copyright owner and the year of first publication. The assertion of copyright may be emphasised by the phrase “All rights reserved”, and in the case there are any lingering doubts the reader may be warned that “No part of this publication may be reproduced or transmitted in any form or by any means without permission”.

But this is to overstate the case. In principle, a quotation of a “substantial” extract from a copyright work or for any quotation of copyright material, however short, for an anthology must be approved by the publishers of the original work. But there is no fixed rule on what constitutes a substantial extract. In any case, even a lengthy quotation from a copyright work may not be an infringement if it is “fair dealing”…for purposes of criticism or review”.

Difficulties can arise when the identity of a copyright holder is unclear. The publisher of the relevant book may have gone out of business or been absorbed into a conglomerate, leaving no records of the original imprint. Detective work can be yet more convoluted when it comes to unpublished works. When copyright holders are hard to trace, the likeliest source of help is the Writers and their Copyright Holders project, otherwise known as WATCH. A joint enterprise of the universities of Texas and Reading, WATCH has created a database of English-language authors whose papers are housed in archives and manuscript repositories. The database is available free of charge on the Internet. If, despite best efforts, a copyright holder cannot be found, there are two options: either to cut the extract or to press ahead with publication in the hope that if the copyright holder does find out he will not object or will not demand an outrageous fee. The risk can be minimized by an open acknowledgement that every effort to satisfy the law has been made.

With the 1988 Copyright Designs and Patents Act, the European concept of “moral rights” was introduced into British law. The most basic is the right of “paternity” which entitles authors to be credited as the creators of their work. However, paternity must be asserted in writing and is not retrospective. No right of paternity attaches to authors of computer programs, or to writers who create works as part of their employment, or journalists, or as contributors to a “collective work”, such as an encyclopaedia, dictionary, or year book.

A second moral right is that of integrity. In theory, this opens ways to forceful objections to any “derogatory statement” if derogatory amounts to “distortion or mutilation … or is otherwise prejudicial to the honour or reputation of the author”.

Moral rights may “be waived by written agreement or with the consent of the author”.

Writers trying to sell ideas should start on the assumption that it is almost impossible to stake an exclusive claim. So much unsolicited material comes the way of publishers and script departments, that the duplication of ideas is inevitable. A writer who is nervous of the attention of rivals is best advised to maintain a certain reticence in dealings with the media.

Next: 49. Contracts.

Whenever a number of people co-operate on a project to a timescale, and with a common end in view, it becomes necessary to introduce some form of planning. Effort needs to be dovetailed, resources allocated with maximum cost-saving efficiency; foreseeable breakdowns avoided, and any potential frustrations or wastage eliminated.

In industry, the most applicable methods of planning involve the construction of a network. Technical authors may have to work within the compass of a project network or, if the documentation itself is of sufficient complexity, construct one themselves. This section briefly outlines the essential facts of network planning techniques. More specific information can be obtained from bundled documentation with relevant software packages.

At its broadest, planning usually involves the following elements:

* Objectives.
* Necessary steps to meet objectives.
* Estimates of time and resources needed to meet each step.
* Risks and contingencies.
* Total time required.
* Total cost.
* Alternatives.
* Decision.
* Establishing schedules.

As a further refinement we may say that a project will be based on:

* Policy.
* Objectives.
* Planning.
* Scheduling.
* Control.

If all this seems fairly elementary, it’s surprising how at least one of these simple elements can be left unattended and cause untold grief at later stages of the project. It’s just as well to spell everything out at the start and instil everyone with the confidence that it’s “all under control”. Good planning is almost always about remembering the basics and building complexity on top of them.

The relationship between these various elements is essentially dynamic and in a state of constant tension. In large projects, imperfections and deviations are always present and should be anticipated, not swept under the carpet. Efficient linkage and channels of communication are therefore crucial if the whole edifice is not to crumble into chaos — a far more likely outcome in most cases that elegant perfection!

One of the methods employed to achieve this is the network plan. As constituted, the planning network forms a subtle and responsive management control system, integrated in depth, and permitting analysis of data and subsequent control of uncertain situations. A carefully constructed network will:

* Define future work.
* Compare supply and demand of resources to improve schedules.
* Improve logistics of resource supply.
* Allow tighter financial control.
* Monitor project progress.

In most forms of networking, nodal points are defined (usually represented as boxes or circles) depicting specific events or distinct particulars of the project. Arrowed lines between the nodes signify activities or elements required to attain the intervening stage. These relationships are constructed at first without reference to time or dates. Subsequent analysis of events by time reveals a series of concurrent and interconnected processes, each with its own scheduling logic. The total time to complete the project is represented by the most time-consuming path through the network, the critical path. This is the minimum time necessary to finish the job.

Other, shorter paths, have certain amounts of leeway built into them, known as slack or float time. Any delay here will not imperil the project’s completion date. But a hold-up on the critical path will inevitably prolong the project and disturb the schedule. This method of networking is known as Critical Path Analysis (CPA) and is one of the most useful tools in large project management.

Another hoary old system is the Project Evaluation and Review Technique, or PERT. The main difference between the two methods is that PERT is event-orientated in that it analyses the events, or turning points, of a project, while CPA is activity-orientated.

Networks may also be hierarchical, or subdivided into levels — as with DDS and FIMS. There are multi-level networks, in which the subdivisions are in tiers of higher and lower level networks, a sort of three-dimensional formation.

A further variant is the sectionalised network, which simply splits the total plan into small parts for the sake of convenience. An author may well get such a piece of a larger network depicting the documentation schedules and activities.

It sometimes happens that different, though related, projects are linked by consequence of common management or resources, or simultaneous completion dates. In these cases, multi-project networks of great sophistication (and vulnerability) are often devised. This is usually achieved by creating a mathematical model in which every element and potential problem is rigorously defined. Every possible intangible is reduced to numeric data, and all imprecisions quantified. It should be obvious to the student that this approach borders on voodoo and the outcomes are often just as speculative.

Next: 48. Copyright.