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.
First: thank you for the courtesy of your considered reply.
Second: I don't know if I am writing to your business or private
address as I have long since discarded your original email. I hope
this is the appropriate one for you.
Third: I agree fully with your points about users - they really ought
remember WIDRIF - when in doubt, read the instructions first.
Fourth: there are a number of structural or systemic problems with
software documentation, that make it much harder for users to find
their way around than in, say, an installation and maintenance guide
for electrical switchgear (though that has its own difficulties). The
main difficulties I see (which I enlarge on the in the paragraphs
below), both as a user of systems and as a writer and reviewer of
software and documentation, include
* unsuitable GUI design,
* documentation left too late,
* Browser immaturity,
* poor context help,
* ill-considered index and find,
* not using Single Sourcing, and
* Headless Menus.
But it is easy to be critical, and I am rarely satisfied with my own
output, either!
I do at least partially subscribe to the theory that perfect GUI
design is so intuitive (or at least so conforms to widely accepted
conventions) that manuals and help files ought never be needed. But
sometimes our GUI writers do counter-intuitive things, and then UPS -
us poor scribes - have to try and explain the inexplicable, make
simple the incomprehensible, separate the confounded and generally try
to make a sow's ear of a system at least look in the documentation as
if it were a silk purse.
I really appreciate being brought in to a project early enough to
review the design before the code is cast in concrete, when there is
still time to say "that will confuse the users - they will expect a
right-click to bring up a menu of actions valid for the item under the
cursor" - for example. But I have been in that ideal world only on a
very few contracts.
Help Desk problems are going to get worse rather than better due to
the rapid growth of 'Browser-based' systems for which good context
help mechanisms still aren't widely available. Context help relieves
the users from having to work out where to look, and what to look FOR
in the documentation - and that, as we all know, is the really hard
problem, both for the author/indexer and the searcher/reader.
Good Context Help can reduce the load on the Help-desk. Ideally it
links every field, every error message, every key-stroke, to its own
trouble-shooting page. Yes, it is expensive to produce and is all too
often omitted.
Good Index and Find are also essential in the documentation and help
system, but so often the word you are looking for either isn't in the
index, or it describes something else, or it appears in hundreds of
places and you have no chance of working out which is the one for you!
The indexer who can predict what words the users will seek on, when
they have a specific question in mind, is a prize above pearls.
Writing a Single Sourced, multi-purpose document is intellectually
much harder than writing separate texts for each distribution medium,
or each variant of the software. But done right it leads to a more
usable system, and can greatly reduce the later cost of documentation
maintenance. How? Firstly, the users don't end up searching back and
forth between two authorities to find which one has the particular
answer they need. Secondly so we are motivated to get it right first
time, rather than taking the easy way out and saying "well, they can
always refer to the manual." Thirdly, each change has to be made only
once, which should be cheaper for the same level of 'quality'. Fourth
and finally, the risk of skew between different distribution media is
all but eliminated.
"Headless Menus" cause much, generally unremarked, frustration. These
are the paragraphs, on-screen or on paper, that tell you all about
some important command, but not HOW TO INVOKE IT! Every help screen
which details a procedure must in my view tell you how to get into the
command, from square one, so to speak. As does MS Word 97 - "On the
Insert menu, click Index and Tables, and then click the Index tab ..."
(reproduced from Word97 help files without permission) - but so many
don't!
Finally, for those who have debated how to decide what you should
include:
1. Ask who will be your readers.
2. Ask what you can assume they know
3. Ask what must they know after their reading
4. Subtracting 2 from 3 provides your guidelines
5. Include references to introductory texts for beginners
6. Include references to advanced texts for experts.
And thar y'go - couldn't be easier - everybody completely catered for!
regards
P
========================================================
Peter Collins, VIVID Management Pty Ltd,
26 Bradleys Head Road, MOSMAN 2088, Australia
+61 2 9968 3308, fax +61 2 9968 3026, mobile +61 (0)18 419 571
Management Consultants and Technical Writers
email: peter -dot- collins -at- bigfoot -dot- com ICQ#: 10981283
web pages: http://www.angelfire.com/pe/pcollins/
========================================================
