Re: Do we need to document all UI elements?

["Larry Usselman" <elgrans -at- gmail -dot- com>]

Hi Keith,

I guess that was my message that got diverted to the Spam box...so it goes.
:(

Here's what I originally posted:

In an example like this, I'm reluctant to assume that the user knows exactly
what the "Send" button does. In some cases, it may send the e-mail
immediately...or it may activate the spell checker and require further
action by the user if errors are found. As much as I dislike it, sometimes
you have to hold your nose and write to the lowest common denominator. My
general rule has been to explain every UI element that the user must (or
may) use, no matter how obvious it seems.

In the example above, clicking the "Send" button might activate an edit
function that verifies spelling, checks for proper address formats, etc.
This runs in the background unless an error is found and normally requires
no user input. But, if something is amiss, then the user needs to take
action before the "Send" function is completed. I'm not sure I would
consider this bad UI design (which would require relabeling all those "Send"
buttons as "Verify & Send") but I still feel it needs to be documented.

I think we're basically in agreement; just debating some of the details. :)

On 6/27/08, Keith Hood <klhra -at- yahoo -dot- com> wrote:
>
> I'm trying to respond to a message I can't see; please bear with me.
> Someone posted a message on this thread and it showed up in my spam box.
> When I tried to mark it "not spam," the message was deleted so I can no
> longer refer to it.
>
> Anyway, the writer addressed my point that I thought it was unnecessary to
> document UI elements that were glaringly obvious, like the "Send" button on
> an email program UI. He said that in some cases, the "Send" button might do
> something different from expectations, like trigger a different program
> instead of simply transmit the message.
>
> In a case like that, obviously the user needs to be warned that what he
> sees might not be what he gets. It's part of the job to check the UI element
> and ensure it really does what it says, before deciding whether to write
> something about it. We're not supposed to stop at seeing if it quacks like a
> duck, we're supposed to also check that it swims.
>
> But also, in a case like that, someone is guilty of bad UI design, and the
> other thing the tech writer needs to do is send information back up the
> project chain to report a usability problem. It may not make any difference
> in a company that is not concerned with usability (and there are some), but
> it's the right thing to do.
>
>
-- 
Larry Usselman
Harrisburg, Dauphin Co., Pennsylvania
My Photos: http://www.pbase.com/snargle
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.