TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Manufacturing Manual Advise From:Stuart Burnfield <slb -at- FS -dot- COM -dot- AU> Date:Tue, 19 Mar 1996 11:06:23 +0800
Greg Moser <76462 -dot- 2004 -at- COMPUSERVE -dot- COM> wrote:
> I have a task of writing a manual that will be submitted to the US
> Government to fulfill a contract requirement.
Many managers think this is why manuals are written. In a few cases, it
may even be true. Nevertheless, you don't have to accept it. Writing a
manual for a government is not rewarding. Writing one for people can be.
Who needs to know about JPATS? What information would help them to do their
job? Write it down and think of ways to help them find the right piece of
information when they need it -- an index, table of contents, list of
figures, clear headings.
You don't say whether the thing you're documenting is software, hardware,
maintaining the plane, flying the plane, booking package holidays on the
plane, or what. This makes it a little hard to be specific, but the
golden rule is: don't describe the thing, and don't describe what the
thing does; describe how your reader can use the thing to help them do their
job.
Dual documentation: will your reader also have access to the internal
documents? Will these documents be in the same bookshelf? Room? Building?
Somewhere else? If they will have an up-to-date copy close to hand, you
can simply refer to the document, section, paragraph, etc. If they won't
have a copy of these internal documents or their copy won't be up-to-date,
and if you're book won't be updated, I don't see what you can do. Copy
the relevant bits into your manual and put the source and the date last
updated next to them.
Other people on the list will give you good advice. You're starting to
ask the right questions. Good luck -- let us know how the project goes.
Regards
---
Stuart Burnfield (slb -at- fs -dot- com -dot- au) "Ask not what your thing
Functional Software can do; ask rather, what
PO Box 192 you can do with your thing."
Leederville, Western Australia, 6903 (JFK on Tech Writing)
