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: context-sensitive help and the printed manual From:"Brierley, Sean" <Sean -at- Quodata -dot- Com> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 22 Jun 2000 09:31:55 -0400
Hallo:
Are you saying that you have an application book, or tutorial book, and want
to create a reference-book-based online help system from it? I think you
should base your online help on a reference book or create online tutorials
from your application guide.
If the reference information you want in your online help does not exist in
your book, you have to add it. Thus, if you want to describe and define
parts of a dialog box, and that information is not present, you'll have to
add that information to the existing book, or write a new book.
You could use FrameMaker's conditional text to write online-only information
and provide online-only screen shots, you could create two books that share
some chapters and don't share others: that is, have chapters intended only
for online and chapters only for in-print. However, it really sounds like
you need a reference book and don't have one. It also sounds like project
management was kind of off-the-cuff. Did your programmers consider whether
the current documentation was suited to context-sensitive help before
including the buttons and, overall, how did the project consider the time
and resources needed for documentation for context sensitivity?
Best regards,
Sean
sean -at- quodata -dot- com
> -----Original Message-----
> From: Alison Tartt [SMTP:akt -at- att -dot- net]
>
<snip> so the structure of the manual was totally task-driven
(Creating
> Customer Accounts, Updating Customer Accounts, etc.). Menus, screens, etc.
> were explained only in the context of a task.
>
> Do I include the
> procedure with the overview of the dialog box, or just create a jump
> (online) or cross-ref (printed) to the procedural topic? And where do I
> place all these topics about screens and dialogs in the printed manual?
> Just after the related topic? (Unfortunately, some dialog boxes do more
> than one thing.) Eventually I have to document every menu and command
> within topics (there is no "What's This" help), and I'm also wondering
> where that kind of material will appear in the printer manual.
>
> TIA,
> Alison Tartt