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.
> From: Keith Hood [mailto:klhra -at- yahoo -dot- com]
> My boss said that he wants the user
> guides to be the best in the world, which, knowing him
> is not all that rhetorical. He also said he wants the
> user docs to explain to the user everything that can
> possibly be explained about the software.
<...>
> By the way, the software I'm working on is used to
> track the movements of charter aircraft, so it has to
> be designed so the actions of users are in accordance
> with FAA regulations.
You scare me. "Best in the world." "Explain 'everything'." Designed "in
accordance with FAA regulations." ???
It sounds like your boss is trying to prevent the need for future training
and technical support for the software. This will not happen. Users
require manuals to operate the software, but user manuals, no matter how
good, will never replace the human intervention of training and technical
support. Theoretically, a manual that does replace human intervention will
account for all possible users of the system and answer all of their
questions before the questions are even asked. Questions such as those from
the most basic users that still need learn how open an application session
to the most savvy users that want streamline operations.
If it was possible to produce a document that accounted for every possible
user, don't you think that Microsoft, Adobe, and Apple would write their
manuals this thoroughly to attract more people to their software? Adobe
could really benefit from such writing. As it is, software support
documentation is generally incomplete with respect to answering every
possible question and there are hundreds of books available for sale to
answer questions that the software makers do not answer.
Perhaps if your manager's request was qualified by saying that the document
should explain everything that can possibly be explained about the software
"in a document written for the average user and addressing the typical, but
not all, issues." According to FAA regulations, of course.
Your organization of user level documents might get confusing. You do need
the user (operator) manual. The reference documents that you mention could
be appendices if your document does not address the user interface and
operations of the document, but your document should discuss these as they
apply to using the system. I hate callouts (personal preference). I don't
see why the user needs to know about the design details. The QRG could also
be an appendix or one-page pull-out, if necessary, but it would defeat the
need of "explaining everything" because a QRG cannot explain everything.
Your FAQs should be a live document, either a web page or a doc on a file
server, that is updated with questions that are frequently asked, of course.
You should have dictionary, glossary, data dictionary, or multiple lexica
depending on your needs to support your software and the applicable FAA
regulations. Sometimes, contact information for support is good in the
event that the documentation does not explain "everything."
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
