Documenting dialog box selections

Subject: Documenting dialog box selections
From: Chris Tolliver <Chris2 -at- IMPACT-TECH -dot- COM>
Date: Mon, 19 Jul 1999 17:21:50 -0400

Title: Documenting dialog box selections

Dear TECHWR-Lers,

How do you document a dialog box where your selection for the main field (control, prompt) determines what other fields are available? Is it better to have one section describing all possible fields or to have multiple sections documenting each "set" of fields? (My search of the archives was fairly fruitless. If this question has been discussed before, please suggest keywords for searching.)

Here's a specific example. On the Trust Information dialog box, the first, main field is a drop-down box titled "Trust Type." For Trust Type, you can select: Grantor Retained Trust, Charitable Remainder Trust, or Qualified Personal Retained Trust. The remaining contents of the dialog box change, depending on what you select.

My colleague prefers to document this dialog box in one section titled "Adding Trusts." This section would document all possible fields with a note saying some fields are not available, depending on what you select for Trust Type.

I prefer to document this dialog box in three sections titled, "Adding Grantor Retained Trusts," "Adding Charitable Remainder Trusts," and "Adding Qualified Personal Retained Trusts." To me, this method puts the burden of interpreting the interface on us writers rather than on the users.

FWIW, most of our users are successful salespeople who are comfortable with computers but who may not know all about the domain -- life insurance. I have not polled users about this question, but I could.

Christina Tolliver
Manager, Publications
Impact Technologies Group, Inc.
Charlotte, NC
chris2 -at- impact-tech -dot- com

Previous by Author: Re: Volunteer in Toronto
Next by Author: Update on upcoming Tech Writing Classes
Previous by Thread: Re: awkward sentence -- preposition at end
Next by Thread: Re: Documenting dialog box selections

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

Sponsored Ads