Navigation links at
the bottom of the page
|
|
|
Navigation links at
the bottom of the page
|
| How to write a Manual | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
|
The outline is your writing plan. You have to have an opening statement,
an introduction, the what of the six W questions journalists ask to
write a good news story. Look on this as the introduction, the hook
with which you'll capture the reader's attention. And you need a barb
to make the hook stick.
Remember John Bunyan
and the reference to his spending twelve years in jail for preaching without
a licence at the beginning of this course? That was the hook. The barb to make
it stick was the reference to Pilgrim's Progress as an example of simple writing.
And again, the listener's image of a flat earth disk resting on the back of
a turtle. That was another hook and turtles all the way down as a continuum
of logic was the barb to make the image stick.
A writing outline is
to a writer what system and manufacturing drawings are to a manufacturer.
Manual outline Front end matter Title page: Title, address, and date Preface or Foreword Introduction
Description Receiving and packing Installation Commissioning Mechanical operation Electrical controls Operating maintenance Mechanical maintenance Electrical maintenance Definitions Appendices References Bibliography Index WORK ESTIMATE Next, you must have a measure of the work required to research and
write your manual. Why? Because writing is no different from any other
work, physical or intellectual. For example, if you install equipment
and are experienced in that field of work, you know how long the installation
will take. Someone somewhere has to know how long it takes to design,
manufacture, install and commission equipment. If they don't you will
not be in business for long. A writing project is no different.
To estimate the work required in an writing project you must first
have a good idea of the scope of work involved. This text has given
you the elements of a manual, the outline. The scope of work is different.
HOW TO WRITE A MANUAL Scope of work Example:
The point about estimating is that it gives you the cost and effort of a writing project. It's no use saying, 'But I don't know how long it's going to be before I start. How can I?' This is something for you to decide. Sample WORK estimate The following work estimate was for an operating manual for a coating-head plastisol line.
Work estimate in hours
On the particular job from which this sample estimate is taken, the
actual time expended was well in excess of 500 hours. This stemmed
from the client taking more time to review and correct the technical
content than had been estimated. The lesson from this is that the longer
the elapsed time of a writing and publishing project, the more time
is expended and, therefore, the higher the cost. Research
What is meant by research? It is the data on which the report will
be based. It could be in the form of tables, interview records, bibliographic
references, historical records, information from a multitude of sources.
If you're dealing with accounts, operating budgets, manufacturing
cost estimates, and statistical analysis, there may not be a great
deal of research. You still have to think about what you are going
to write and it is all part of your research.
If you're discussing
a design proposal, manufacturing and production procedure, sales strategy,
marketing plans, purchasing or personnel policies there might be considerable
research to do. As in the case of testing, say, a new smoke and odour filter
for commercial kitchen ventilation, there might well be an extended period
of testing and test results to analyze; that's research too. In any case, know
your facts and make allowance for the time involved when making your estimate.
House style
Many corporations and institutions have an accepted, or required, method
of report lay-out. This is something as distinct from editorial content.
The writer in such an organization has no choice in the matter. Similarly,
if the report is destined for publication in a journal or as part
of the proceedings of a professional society, the rules of lay-out
are equally inflexible. Such rules affect the physical appearance
of the final document.
The words, arguments
and impressions conveyed are those of the author or authors of the paper. The
way in which those views and opinions are physically laid out on the page,
as well as such matters as syntax and spelling convention, is often dictated
by others. The views expressed here are intended for general application only
and have to be applied in conjunction with the 'house style' of the organization
to which the writer or writers belong.
House style is the name
given to the form, lay-out, paragraph numbering, punctuation and even spelling
required by some organizations. All publishers have a house style and an increasing
number of corporations are adopting the practice. Preferred spelling, for example,
might be 'program' (American English) as opposed to 'programme' (British and
Canadian English). In recent years Canadian English has tended to follow American
spelling, although this is not an invariable rule.
Going by the formats,
lay-outs and styles of many documents of government - regulatory documents,
notices, guides, consultative papers et al - there is no set format or, in
a phrase, house style.
Writing instructions Most magazine, journals and periodical publishes issue writing guidelines for contract writers. Those guidelines or instructions vary from publisher to publisher. The following instructions, used for sample purposes here, are those of Delta Tech Systems, published under the heading INSTRUCTIONS FOR TECHNICAL WRITERS working under contract or on assignment. The sample documents referred to in the instructions, however, are not included here. INSTRUCTIONS FOR TECHNICAL WRITERS These instructions are to guide writers and to help them produce draft copy that meets our house style and editorial standards. The package includes
We expect writers to use the information supplied as a basis for writing draft copy on the project assigned to them. The following information is a statement of the minimum requirements of writers working for DTS. It is your job to research, organize, outline, and write draft copy on the subjects and topics assigned to you. DTS editors and the production department will prepare the illustrations, typeset the copy and publish the finished product. Project plans Preparation
As directed in your written assignment, keep a work journal. Record
the date, time, place and detail of your research, interviews conducted,
and references. Research the task thoroughly and make sure you keep
an annotated record. You might need to answer questions put by the
editor or the client or both.
When you have enough
information to start the work, write an outline. It is not our purpose to tell
professional writers how to write an outline for a major writing project. Read
the handbook provided. As a guide, our editors expect to see a ten to fifteen-page
outline per hundred pages to draft copy.
Submit the outline for
the editor's approval and discussion before you begin writing. This is a mandatory
requirement of our work method. In addition, you need to discuss the outline
with the client and obtain the client's approval before you start writing.
We will not accept draft copy that has not been preceded by a working outline.
Work outline
A working outline is your writing plan. This does not mean it cannot
be changed once you begin writing. It does give the editor a clear
understanding of what to expect when he or she starts editing your
draft copy. We require complete outlines: front end matter; chapter
or section headers; intention to include appendices, bibliography
and index; topic headings within chapters; main points by topics.
Draft copy
(Editor: place Figure 1 here)
(Chapter ends)
Figures and illustrations
Most technical publications include illustrations. Delta Tech illustrators produce the illustrations you require. You must, however, write clear instructions to the illustrator. That is, name the figure, table or illustration by number and title. Number your figures sequentially and your tables sequentially throughout the work. Avoid complicated figure numbering (e.g., 1-5, A-I, Fl-b, 1.5.6.3.2) like the plague; table references likewise. When choosing illustrations,
aim for simplicity. Most drawings include more detail than is necessary for
illustrative purposes. Select a two-dimensional illustration in preference
to an isometric view. Produce sketches of boxes, organization charts and flow
diagrams. The illustrator will look after the rest.
When indicating in your
text where you would like the illustrations to go, understand that it is not
always possible to place figures where the writer wants them. There are type-setting
and page lay-out problems to solve. This is the editor's and production lay-out
person's problem to settle, not yours.
Publishing deadlines Progress reports |
||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
