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: Menus and Toolbars From:jlshaeffer -at- aol -dot- com To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Tue, 15 Jan 2008 10:21:59 -0500
Case A: As a user, the description of Procedure A may not be the right one for me. That is, the procedure that I would like to follow may include a feature that is not documented in Procedure A. I really want procedure F, but I don't know that until I look at reference-style material for that intriguing feature (which, one hopes, leads me to Procedure F). This might also be solved by the "good index", but even "good indexes" can get a user out-of-context in a hurry. Scanning a list of features while I'm on that dialog or page may be more efficient.
Case B: Some features may be used under certain conditions and not others. Documenting a procedure while laying down a trail of all the possible if / then variations can be too confusing and too time consuming for everyone. Mix in the GUI interface options of having 4 ways to do each thing and nobody can follow any sensible path through the text. There are ways to handle this and one is to simplify the documented procedure and handle the outlying conditions by explaining the features as features. Then the users can customize their own recipes.
Case C: As a user, I may end up creating my own "Frankenstein's Monster" of a Procedure cobbled together out of a bunch of features that no developer or writer ever thought of putting together. If you've been in software for any length of time you've seen users do this. Learning about these creations is one clue as to how one's software can be improved.
Case D: As a practical matter, doing task-based documentation makes it hard to assure completeness. Reference-style documentation doesn't put the pieces together, but at least everyone can be assured that the pieces are covered. (Management wants to be able to say that the information is somewhere in the documentation. Where it is in the documentation is a secondary or tertiary concern. I'm not praising this attitude, just pointing out that we live with it.)
Janice Gelb wrote:
Could you explain a little further? I'm a
little confused why scanning menu lists would
be quicker than seeing the menu option in the
procedure description of the task you're doing.
I agree that procedure headings need to be explicit
and the doc needs to have a good index, but I figured
we were assuming that the documentation was good
other than this question.
More new features than ever. Check out the new AOL Mail ! - http://webmail.aol.com
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-