Tech Biz Writing

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.

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

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.

When the first draft has passed through the two loops of the development phase flowchart, it should be both technically impeccable (or as near as possible to it) and editorially beyond reproach. The time has now arrived to assemble the final draft for submission to the production people.

The final draft must be perfect in all respects, with full instructions for the production team attached, and all points of the specification observed punctiliously. Any changes demanded by the vetting authority and editor should have been incorporated, and the author’s final polishing attended to. If the book is to be lithoed, there should be full agreement on the draft by all concerned before camera-ready copy is produced.

At this point a number of smaller tasks must be tackled. The preliminary pages (prelims) should be prepared. These include title page, contents page, key to abbreviations and others depending on the type of publication. Also the end pages, which may comprise a bibliography, acknowledgements, and an index. However, the average technical document may contain few of these, and it’s the house style which will dictate on these matters.

Unless a disk copy is to be used directly for print, when preparing copy for a compositor, page designer or typist, the following points should be observed:

* Use double spacing.
* Use only one side of the paper.
* Make sure the MS is legible.
* If written, use black ink.
* Number each sheet
* Circle any instruction to the typist.
* Conform strictly to house style or spec.

It has been estimated that, on average, a typist makes three errors per page. Some, it has to be said, are much better than this, though others are worse. Suffice it to say, it would be a very unusual typescript that arrived at an author’s desk without a single typo. The typescript should be very carefully checked at this stage (page proof). This is the final version. Major author corrections — or changes of mind — are definitely ruled out now. You had your chance. Your fate is sealed!

Next: 32. Commercial Books.