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
