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:PDF online manuals, take II From:Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA> Date:Thu, 29 Jul 1999 14:34:47 -0400
Susana Rosende provided more details on her company's
decision to move towards online documentation in PDF
format:
<<...our company was unable to use context-sensitive help.
Blue-Sky bluntly told us that they don't support PowerBuilder
applications.>>
Have you asked the same question of the PowerBuilder
people? It's quite possible that they can suggest how to hook
a WinHelp file into their applications. If not, it sounds like
you do indeed need to adopt a non-WinHelp solution.
If you do, there are still many other things you can do to
provide semi-context-sensitive help. For example, add a
simple phrase at the bottom of each dialog box: something
like "For help on this topic, see page XX of the online
manual". Alternatively, include a simple, unique code such as
"Print dialog" that matches the keyword(s) you used in the
PDF file; that way, users can search for those specific
keywords. (The corresponding phrase in the dialog box
would be something like "For help on this topic, search for
the phrase 'print dialog box' in the online help.") For things
like menus, icons, and other screen debris, you can have the
programmers display "what is this?" help in the status line at
the bottom of the screen; that's easy to program even if
PowerBuilder doesn't support this directly.
<<Second, our clients... prefer books to online doc. They are
used to sifting through tomes and always print the online
help, anyway.>>
Even if "always" only means "in more than 50% of the
cases", that suggests to me that you'd be better off producing
good printed documentation, with the PDF files used solely
for updates. First off, if your clients are attorneys, they won't
balk at the tiny additional cost of documentation (typically
less than $5 U.S. per book for a typical 200-page manual); it's
certainly cheaper than them having to print the same thing on
a laser printer and then bind it. Second, if they're only going
to print the online help, then spending a lot of time
developing it probably isn't all that useful. Your idea of
providing the manual online in PDF format _in addition to
the printed manual_ makes a great deal of sense in that
situation: for the few who want to use the PDF to search for
help, they at least have that option.
<<Our project manager is now requiring the trainers to
include online help training to cut down on support costs. Our
programmers are redesigning our application to be more user
friendly.>>
Sounds like the latter part of the solution is the better way to
go. The holy grail of software development is to produce an
interface sufficiently intuitive that it requires no
documentation. That's probably unrealistic for some time to
come, but in the meantime, this makes you a valuable asset to
your company: you're the one who can act as user advocate
and make sure that the application really is user-friendly.
Most developers lack the empathy or training to truly
understand what users want and need; as a technical
communicator, you have the expertise to find this out, and
should work with them to ensure that they produce what is
truly necessary.
