Re: Do we need to document all UI elements?

Subject: Re: Do we need to document all UI elements?
From: "Larry Usselman" <elgrans -at- gmail -dot- com>
To: klhra -at- yahoo -dot- com
Date: Fri, 27 Jun 2008 11:15:43 -0400

Hi Keith,

I guess that was my message that got diverted to the Spam 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:

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.

Re: Do we need to document all UI elements?: From: Caroline Tabach
Re: Do we need to document all UI elements?: From: Keith Hood

Previous by Author: Re: Do we need to document all UI elements?
Next by Author: Re: Interesting quote
Previous by Thread: Re: Do we need to document all UI elements?
Next by Thread: Re: Do we need to document all UI elements?

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

Sponsored Ads