Re: Do we need to document all UI elements?

[Keith Hood <klhra -at- yahoo -dot- com>]

I would answer no, sort of, because there are some UI elements that I think don't need to be documented under any circumstances. These include framing elements like the title bar at the top of a dialog box. There's no point in wasting your time to tell the reader that bar shows the name of the dialog box. Or the names of the tabs at the top of a multi-tap wizard. The user is probably interested in tasks, rather than exploring the UI, so he wants to be directed to the right tab to click, but he doesn't really care about getting an explanation of the differences between the tabs.

Basically, I think it all comes down to asking two questions about each element: Does the user need information about this element in order to perform the action correctly? Would information about this element reduce the probability of the user making an error?

Some other controls, I think do not need to be documented if their nature and use are unmistakably obvious. For example, a "Send" button on an email interface - I think that's obvious enough that the average user can figure it out with no real problem. Of course, you do still have to consider the nature of the anticipated user. There are some elements that perhaps are not that obvious to someone who's not quite as experienced or as intelligent as you are.

And, you should document controls that have any variability. If the UI includes option buttons, for example. In that case, the action taken by the software branches depending on which button is selected, so the user needs an explanation of the effect of choosing one of those buttons, in order to make a reasoned choice. Also, you should document any variations in the nature of inputs. If a dropdown list gives you choices, the user may need information to indicate which choice is the most correct for his needs.

Last, you should document any requirements on user inputs. If a field requires all-caps text, if date inputs must follow a certain format, etc.




> On 6/25/08, mallikarjuna prasad
> <mallikarjuna999 -at- yahoo -dot- co -dot- in> wrote:
> >
> > Hi,
> >
> > Do we need to document all UI elements?
> >
> > Cheers
> >



      
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.