Tech Biz Writing

Contacts
Points for approaching a contact:

* Areas needing clarification
* Queries on modifications
* Technical interpretation
* New information.

A visit should accomplish:

* Points answered
* Queries clarified
* Equipment examined
* Way paved for next stage.

Meetings
Chairman’s main considerations:

* Is meeting necessary?
* Who should come?
* Are they available?
* Subject of discussion?
* What is to be achieved?
* Start/finish times?
* Venue?
* Advance information?
* Supplementary topics?

Agenda
The agenda of a meeting will usually contain:

* Place, time, and date
* Subject
* Order of discussion
* Other business.

Next: 54. Outline and Design Part 3.

Requirement
Identification of requirement: The adjacent points identify the key areas in eliciting a client’s requirements:

* Specification
* Target readership
* Deadline
* Information available
* Maintenance philosophy
* Subcontractors involved
* Commercial parts incorporated
* Author’s contacts
* Validation procedure
* Editorial procedure
* Documentation meetings.

Specification
Specification is a document prepared by an authority as a basis for the production of technical literature. In addition, we use this term to cover the format, length, and presentation of the document. As well as British Standards, there are many military and civil specs.

Outline design
The outline design anticipates:

* The information an author will need
* The synopsis of the document
* The cost estimate of the work to be done.

It summarises both the specification and the requirement, and looks forward to the sources and type of data that will be needed.

Sources of information
Types of information: Information may come in three ways:

* Printed information
* Verbal information
* Visual information.

The British Library: The national library of Great Britain which has a number of branches useful to the technology researcher.
Classification system: Methods — numeric or alpha-numeric — of allotting to publications a specific classification which distinguishes them from others.
Information search sequence: The following step by step sequence outlines a logical procedure for researching information at a library:

1. Establish subject areas and terminology.
2. Extract classifications from library catalogues.
3. Search index and directories for relevant publications.
4. Order publications not available at library.
5. Compile bibliography of the subject for further research.
6. Consult periodical indexes for state of the art data.
7. Obtain details of trade papers and journals from press guides.
8. Make list of relevant research organisations.
9. Examine year books for appropriate standards and specs.
10. Look through Patent indexes for useful information.

Universal Decimal classification: A ten-point classification system of which Class 6 refers to Applied Science and Technology, and 62 covers Engineering Sciences.
Library of Congress classification: An alpha-numeric method used to classify the publication stock of the US Library of Congress.
International Standard Book Number: A number prefaced by ISBN and found usually on the history page of most published books. Used extensively in computerised and tele-ordering systems.

To be Continued

Next: 53. Outline and Design Part 2.

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.