Documenting dialog box selectionsTitle: Documenting dialog box selections
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.
Impact Technologies Group, Inc.
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
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites