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

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.

The role of the maintenance engineer has changed dramatically over recent years. With the increased complexity and turnover of hardware devices, it has not been possible to train him sufficiently within the time available as in more expansive days. One of the consequences of this is that the diagnostic/maintenance engineer develops a range of systems skills at the expense of a thoroughgoing knowledge of discrete component technology. He also makes use of a number of modern aids, including specifically designed documentation.

One of the simplest and most cost-effective ways of maintaining a complex system is by the use of an algorithm — usually expressed as a flowchart — or a Functionally Identified Maintenance System (FIMS). An algorithm is a step-by-step procedure, or list of instructions, for a process. A recipe is an algorithm; so is the mathematical base of a computer program.

A flowchart is a diagram representing an algorithm. Certain symbols are taken to depict nodal points in the process. A diamond shape signifies a decision point, the question being formulated within the block, and two of the angles representing yes and no exits. Similarly, a circle is used for a terminal point, either the beginning or end of a process, or as a link to another sheet. Flowcharts are useful, not only in computer programming, but also as a means of simplifying a complicated diagnostic/maintenance procedure. In such a system, the engineer is given a series of specific actions or observations. Questions are posed, to which the answer is either yes or no — proceed or perform some action.

A related method, but of wider scope and applicability, is the Functionally Identified Maintenance system. The FIMS concept is based on functional flow diagrams which depict functional sequences rather than hardware boundaries. The documentation provides the maintainer with a coherent test strategy, logically presented at various levels of complexity. Each level follows on from the preceding one, allowing a structured approach to maintenance not unlike the program steps running a computer.

Fault diagnosis is a logical process beginning with an “overview” and moving down to a lower, or detailed, levels. Certain definite stages may be isolated:

* Collate and analyse symptoms
* Examine equipment.
* Locate fault(s) and cause(s).
* Repair or replace faulty part or unit.
* Test performance.

FIMS documentation reflects this process using a variety of formats at each of three or more levels:

* High or “master” level — general overview showing major functions.
* Intermediate level(s) — functional subsystems within each major function.
* Low level — the most detailed level.

Functional block diagrams depict functional flows in a left to right direction. Hardware configurations are not relevant to the flow of the diagram, but may be indicated in some way within it.
Functional block texts consist of blocks containing textual descriptions of useful testing information.
Maintenance dependency charts show, in graphical form, the functions and the events which define the dependencies between them. It’s a symbolic charting of the functional block diagram.
Symptom analysis charts sometimes replace the maintenance dependency charts at the higher levels.
Test data charts list test points, setting-up procedures, and interpretation of results.
Layout diagrams revert to hardware boundaries enabling the maintainer to locate precise repair points.
Fault-finding and repair are not always carried out by the same technician. Consequently, a division is usually necessary within the documentation to reflect the needs of both diagnosis and maintenance.

Next: 47. Network Planning.