Re: Menus and Toolbars

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

I'll bite.

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.)

Jim Shaeffer

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 ! -

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.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Menus and Toolbars: From: Ben
Re: Menus and Toolbars: From: Janice Gelb
RE: Menus and Toolbars: From: Jessica Weissman
Re: Menus and Toolbars: From: Janice Gelb

Previous by Author: Standard Doc Set
Next by Author: Remove part of a PDF?
Previous by Thread: Re: Menus and Toolbars
Next by Thread: Re: Menus and Toolbars

What this post helpful? Share it with friends and colleagues:

Sponsored Ads