Navigation links at
the bottom of the page
|
|
|
Navigation links at
the bottom of the page
|
[Editorial note: As with the article on oral presentation
of a technical paper, this article on technical publishing was prepared
at the request of a number of medium-sized clients interested in creating
their own publishing departments. Some of the material included in
this article appeared in previous articles.]
|
||||||||||||||||||||||||||||
| A GUIDE TO TECHNICAL PUBLISHING | ||||||||||||||||||||||||||||
|
Many commercial organizations and institutions operate well-equipped
departments to publish illustrated manuals, reports, specifications,
spare parts records, technical papers and marketing publications. Indeed,
some print departments are as well equipped as professional print shops.
Not even the best production equipment, however, guarantees a high-quality
publication; that depends on the effort and organization that goes
into preparing the camera-ready copy in the first place.
Many large and successful
book publishers do not own a single item of printing equipment other than the
same copying machines that can be found in any business office. The major work
that goes into the books they publish is done by others under sub-contract:
the type-setting, art work, lay-out, galleys and print production. This leaves
the publisher free to concentrate on organizing and overseeing the more important
work of writing, editing and proof-reading. Many enterprises that have their
own document departments fail to distinguish between the writing and editing
side of the work (the two, intellectually creative elements of publishing)
and production of the finished product (type setting, colour separation and
actual printing).
Desktop publishing has
changed the publishing field immeasurably and given even the smallest organization
the means of producing its own publications. Yet the production and publication
of a high quality product is still an uncertain affair for those who lack experience.
Publishing can be deceptively difficult for inexperienced publishers. It requires
a firm discipline to avoid errors. For lack of training and experience, many
companies use expensive software and production equipment to publish what a
good typist with a copier can produce at a fraction of the cost.
This guide to desk top
publishing deals with the organization required to produce and publish illustrated
copy. It discusses how to manage a project: how to make sure you to do all
the things any publishing house does to launch a new book. The work needed
to produce technical documents using programmes such as WordPerfect, PageMaker,
Ventura and Interleaf is the same for desktop publishing as for off-set printing.
However, this guide is not a software manual. Most of the instruction manuals
electronic software suppliers write and publish are models of accuracy, style
and format which companies who operate documentation departments could profit
by in producing in-house manuals and documents.
The main difference
between electronic desktop publishing and the work produced by commercial publishing
houses, such as John Wiley & Sons, Prentice-Hall and host of similar publishers,
is the size of print runs undertaken. Even here the distinction is often blurred.
A large publisher may have a print run of thousands of copies; a manufacturer
may need only a dozen copies or so for, say, operating and maintenance purposes.
Small print runs outside the regular publishing industry only occasionally
exceed 1,000 copies. Nevertheless, the work involved in writing, illustrating
and printing one manual is exactly the same as that required for a print-run
of thousands.
ELEMENTS The three elements that produce a good publication are sound management, technical expertise and production know-how.
In terms of work content, the writer contributes about 25 to 30% to the published document; the editor, 15%, the illustrator, 15%; the proof-reader, 5%; the typesetting and lay out, 25%; and project management, 10%. EDITING Only a few engineers, physicists, technicians, technologists and other
specialists working in the applied sciences are good writers. This
is the reality which those responsible for producing technical literature
must face. Therefore, unless a specialist working in a field of applied
science is also an accomplished and proven editor, he or she should
not be given editorial responsibility. An experienced editor who may
have little or no knowledge of the subject of the publication can still
produce accurate technical literature. Many people will query this
statement. Nevertheless, a first-class editor is to a polished published
document what a nuclear engineer is to nuclear reactor: a professional
with whom it is difficult to do without. The editor's main job is edit
text and illustrations to simplify and produce readable copy. This
is the main reason why major technical publishers succeed and many
in-house documentation services produce only mediocre or inferior quality
publications.
In major publishing
houses, commissioning editors use a writing contract to specify the writer's
responsibilities. The publisher sometimes pays the writer an advance royalty
and a set royalty fee for each copy of published work sold. The writer submits
draft text and suggests illustrations for editing, but has no authority over
such matters as the house style (grammar and syntax) used, the layout, type
style, type-setting, quality of illustrations, printing and publication schedule
of the product.
A project manager (or
more properly, a project editor) in a commercial enterprise is in the same
position as the managing editor in a publishing house. Unless managers recognize
and acknowledge this distinction they will jeopardize the quality of the finished
product. In organizations (engineering, consulting and architectural firms,
government bureaucracies, research laboratories and public utilities) with
engineers and similar specialists in management positions, the need to give
the project editor authority and responsibility for the camera-ready copy is
sometimes hard to accept.
Editing is more than
correcting grammar, syntax and style. It carries responsibility for reading
the text from the reader's viewpoint, not the writer's. It's the editor's job
to set the style, language, layout and format in cooperation with the production
supervisor. It is the editor's job to make the style readable, to eliminate
excess verbiage and to make an esthetically attractive finished product.
Writers working under
contract (to a regular publisher) have copyright ownership rights and in-house
writers, generally speaking, do not. Copyright ownership is vested in the organization
unless that organization is under contract to a client. For example, many DTS
clients (Transport Canada and Ontario Hydro are examples) provide the expertise
and own the copyright of the finished work.
TREAT EVERY WRITING JOB AS A PROJECT An equipment manufacturer has a tangible product to sell; so does
a food processing plant, pharmaceutical firm, a soap or vinyl manufacturer.
Even an architect or consulting engineer sells a tangible product in
the form of drawings, specifications, studies and related services.
What a technical publisher (or document department) sells is more subjective
than objective.
Even though another
department in the organization begins the writing project, the document department
should have the expertise and knowledge to provide the time and cost estimate.
The subjective nature
of producing and publishing a large document presents a problem. That is, how
does one measure the work required to research, write, illustrate and publish
a technical document? As explained in The Handbook of Technical Writing first
published by DTS in 1984, one can treat a desktop publishing project with the
same objectivity as, say, a consulting engineering project.
How do consultants estimate,
plan, schedule, control and manage a design project or technical investigation?
First, they understand the client's requirements by thoroughly investigating
the expectations. They use this information to define the scope of work. The
scope of work determines the work content which, in turn, is the road map for
the right people to do the job, to define the work method, specify the controls,
prepare the schedule, and describe the reporting system.
A document department
must use the very same elements to control and manage a writing and publishing
project. Unless it has this control it will not have budget control for the
finished product nor a means to guarantee performance. This may be acceptable
in a bureaucratic organization that pays only lip service to budget controls
and lacks accountability regarding performance; it is disastrous in private
enterprise, which would without strict quality control soon cease to exist.
Writing and translation
projects vary in size and complexity. Some are written in response to well-written
specifications; others to a vague and loose enquiry. Most proposals, however,
are written in response to enquiries from clients who need the work done and
have little or no idea of how to specify requirements. In these cases, a standard
layout that includes these topics makes an excellent foundation for a proposal.
It is immaterial whether the 'client' is another department in the same organization
or an external corporation, company or enterprise. The same commonsense approach
to organizing a writing project applies. To control costs and maintain production
discipline, treat every project as a separate entity, even when handling document
development in major projects involving numerous separate publications. Following
are the important elements of the project proposal.
TITLE PAGE Specify the date, proposal number, title and the issuing office. Include a copyright statement at the foot of the title page. This reserves copyright ownership to the form and content of the proposal, and prohibits its use for any purpose other than that for which it is written. The fact is, publishing
proposals include information of value to the client or would-be client, not
to mention competitors. The information given is a specification that a client
might be able to use to write the work in-house; hence the reason for reserving
copyright ownership of the information being offered.
DISCUSSION Do not use the word 'introduction' to head the opening statement of
a proposal; it is redundant. The reader knows that the opening statement
introduces the subject. An introduction is a straightforward statement;
write what has to be written without adornment.
The proposal is usually
produced in response to a meeting or telephone enquiry. Refer to the meeting
by date, name the people present, summarize what was said, required, requested
or stated. To avoid misunderstanding, state the circumstances in which the
proposal is being written. This is a good lead-in to the scope of work.
SCOPE OF WORK Specifying the scope of work covered by the proposal is the most important statement of facts offered. It is the basis on which one makes the work estimate. As the proposal might become part of the contract document, a clear statement of the scope of work is essential if you are to avoid dispute and argument later. WORK METHOD The method used to execute the project is a logical consequence of
the scope of work. Most publishers have a set discipline for researching,
writing, revising and producing what is called 'camera-ready' or c-r
copy, meaning that is ready for off-set printing by the printer. Delivering
c-r copy cuts out type setting by the printer. The number of draft
copies produced varies widely. Once it reaches the client, draft copy
is subject to many revisions. Some copy is revised and re-submitted
repeatedly, especially when chapters, sections or parts are submitted
piecemeal.
For this reason, reserve
the right to write the first and second drafts to the agreed editorial standard.
After that, it is equally important to agree that subsequent changes are made
to the changes of the client, whether the editors agree with the changes or
not. This puts the onus of the finished product on the client. It is an important
point to avoid extended debate later.
WORK ESTIMATE A work estimate is a specification of the work content based on an
assessment of the scope of work, the expertise required to fulfill
the contract, and the related jobs such as contract printing, bookbinding
and photography etc.
A well-developed estimate
comes from the experience of gauging the amount of research, writing, illustrating,
editing, typesetting and production hours required.
WORK SCHEDULE Once the work estimate is complete, producing a work schedule is a
relatively simple task. It depends on what other work is on hand, the
availability of people and the work load of the department.
The schedule is a means
by which the client, as well as the project manager, can measure progress on
long-term contracts. For this reason, an updated monthly schedule forms part
of the monthly progress report.
PROOF OF ABILITY To assure the client that one is competent to do the work proposed, it is helpful to list similar publishing jobs. In engineering proposals there is a tendency to overwhelm clients with lists of contracts and clients. In preparing writing proposals, it is better to quote similar work done on no more than a dozen jobs or clients or both at the most. The client wants to know that you can do the work, not get a listing of all the work you have ever done. PERSONNEL Choosing the right people for the job is important. Even the largest publishing contract requires no more than a few principals: project manager, editor, writer, translators (usually more than one), production editor, and illustrator and specialist consultants. FEES AND DISBURSEMENTS Specify the categories and hourly rates of people who will work on the job. Apply these rates to the estimated hours of work and the resulting tabulation gives the cost of the project. It is often necessary to visit the client's offices, plant, research library, which means stating travel and living expenses. State what T & L allowances apply to the project. TERMS OF PAYMENT Invoice monthly for work done and expenses incurred during the previous
month for payment at net 30 days of the invoice date. On fixed price,
long term contracts, it is not unusual to apply progress payments for
work done by stages: research complete, first draft submission, c-r
copy complete, publication. When dealing with new clients, DTS occasionally
requires and obtains a 15 per cent down payment.
Clients have responsibilities
as well as the publisher. They are required to supply information, assist in
research, check draft copy, provide space and equipment for visiting writers
and researches. Therefore, in the proposal, include a statement of your expectations
of the client.
If, for example, you
expect draft copy reviewed and returned within two weeks, then the proposal
should include your expectation of cooperation in this regard. Jobs often take
longer than estimated because clients fail to keep copy review commitments.
Costs also increase in direct proportion to increase in the actual elapsed
time over the estimated elapsed time.
CONFIDENTIALITY Technical writing means dealing with proprietary and confidential information. You should therefore require anyone working on projects to sign a confidentiality agreement. State this fact in the proposal. COPYRIGHT Copyright ownership of material is one of the most important aspects
of publishing. Who owns the copyright is a matter for you to decide
with the client. For this reason, technical writing firms include two
standard clauses. One clause states that copyright ownership of the
proposal is vested in the company undertaking to write and publish
the work. It is a repeat of the copyright statement on the cover sheet
of this guide. The second clause may or may not give copyright ownership
of the resulting material to the client.
If a publisher writes
material for a client, including information which derives from the publisher's
own expertise or resources, it reserves copyright ownership. If the client's
technology is proprietary, copyright ownership of the resulting product is
clearly that of the client.
1. PROJECT MANAGEMENT Manage and control a publishing contract by means of a plan. Technical
writing is a subjective matter. That is, research, writing and editing
is an intellectual pursuit. The end result is a written work: a manual,
procedure, technical paper, spare parts lists. How does a publisher
assure the client, or a document department a client department, that
the work is well organized? How do you control the work?
To justify progress invoices, provide the client with objective evidence
of the work done before the end product is produced. This is the purpose
of the work plan and schedule, to give the client a means of measuring
work progress. This section deals with the project organization plan.
To provide writing and
production staff with a copy of the proposal is not sound business sense. Production
personnel may be interested in the value of the project, but they require more
information than the publisher is contracted to supply to the client. Writers
and production staff want to know precisely what to do. This is the purpose
of the project plan. What policies to follow? The scope of work; how is the
work organized? What work methods apply? Who is responsible for what? What
procedure to follow? And what reports, references, files and records apply?
Here is a summary of
the main elements of a project plan, although special contracts may require
additional information.
2. HOUSE STYLE House style is the term used to define a particular set of stylistic
conventions used in published works. Every publisher has a house style,
either developed in-house or a book of style in the public domain.
Some corporations have their own house style. Most industrial and commercial
enterprises, however, do not have a set style and rely on whoever happens
to be responsible for the production of in-house publications.
Developing a style manual
is costly and time-consuming. A number of style manuals are available from
which to choose: the Style Manual of Random House, Prentice-Hall's Words Into
Type and the Chicago Manual of Style are three well-known authorities. Delta
Tech Systems uses The Chicago Manual of Style as its house style, except that
it uses Canadian-English spelling conventions. Other standard references used
include the Oxford University Press Printer's and Authors Dictionary, Fowler's
Common English Usage and Roget's Thesaurus. The production of impeccable c-r
copy, proof-read and corrected, is essential for high-quality publishing. Consistency
of style is equally important: the correct use of punctuation, spelling and
syntax. Client's staff claiming little knowledge of language soon find misplaced
commas and apostrophes. To avoid embarrassment, and when in doubt, use a style
manual.
3. TECHNICAL WRITERS Technical writing is demanding work. With training and disciplined direction, specialists in the applied sciences can become proficient writers. For this reason, it helps to provide writers and would-be writers with clear instructions. Here are instructions to use as a basis for developing specific in-house instructions. Instructions for writers The aim of this publisher (or department or organization) is to publish
illustrated texts, manuals, procedures and instructions in a simple,
straightforward style. Regardless of the subject, the policy is to
publish copy that is easily readable by anyone with a grade nine or
higher level of education.
These instructions are to guide writers. Writers who
follow them will produce draft copy that meets the house style and editorial
standards of the organization. The package includes a number of items.
Writers will use the information supplied as a basis for writing draft copy on the project assigned to them. Following is a statement of minimum requirements. It is the writer's job to research, organize, outline, and write draft copy on the subjects and topics assigned. The editor and 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 checked. Research the task thoroughly and make sure
you keep an annotated record. This is important if you need to answer
questions put by the editor or the client or both.
When you have enough information to start planning
your work, write an outline. It is not an editor's job to tell professional
writers how to write an outline for a major writing project. Read the handbook
provided. As a rough guide, a ten to fifteen page outline per hundred pages
to draft copy is what the editor will expect to see.
Submit the outline to the project editor for approval
and discussion before you begin writing. This is a mandatory requirement of
our work method. Besides, you need to discuss the outline with the client and
obtain the client's approval before you start writing. The editor will not
accept draft copy that has not been preceded by a working outline.
Work outline Draft copy
(Editor: place Figure 1 here)
(Chapter ends)
Figures and illustrations
Most technical publications include illustrations. Illustrators will
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) like the plague; table references
likewise.
When specifying illustrations, aim for simplicity.
Most drawings, for example, include far more detail than is necessary for a
simple line illustration. Select a two-dimensional illustration in preference
to an isometric view. Sketch boxes, organization charts and flow diagrams by
hand. The illustrator will look after the rest.
When marking in your text where you would like the
illustrations to go, understand that it is not always possible to place figures
where you would like them placed. There are typesetting and page layout considerations
to take into account. This is the editor's and production layout person's problem
to solve.
Publishing deadlines Progress reports Project Progress Report for
Summarize in writing and in point form the work done during the period on which you are reporting. The following is a sample summary of the type of information required.
4. ILLUSTRATIONS The two types of illustrations most common to technical publishing
documents are black and white photographs and line drawings. Both types serve a purpose.
B/W photographs illustrate
processes or items of equipment difficult to render as line graphic illustrations.
Photographs take a large amount of electronic memory. In this respect, they
are a disadvantage when using desktop publishing equipment to produce C-R copy.
A 60-page manual with
up to 20 B/w photographs and an equal number of line drawings requires up to
70m bytes of hard disk space. A single page of copy with one photographic illustration
takes about an hour to print. As a result, printing a full-length manual with
photographic illustrations takes a some time.
When contracting to
publish manuals containing photographs, make sure there is sufficient allowance
in the cost estimate to cover the production costs.
In contrast, line drawings done on a CAD programme take less production
and printing time. Line drawings are for this reason preferred to B/W
illustrations, unless the client is aware of the cost and is willing
to pay for them.
5. TRANSLATIONS Many publishers publish material in more than one language. Translators
work from finished, edited and proof-read English version of the text
only. On no account will they work with draft text.
Translators are required
to supply translated copy in the same type style and format that the writer
of the English version supplies (see the instructions supplied to technical
writers). Second language copy, doubled spaced, LH justified only, and in pica
12 type style is then edited, controlled and produced by the same procedure
that the original copy undergoes.
6. CAMERA-READY COPY The production editor supervises the production of camera-ready copy including type-setting, layout, format and pagination. |
||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||
