Re: Documenting the user interface

Subject: Re: Documenting the user interface
From: "Mike Starr" <mike -at- writestarr -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 14 Jan 2007 03:04:53 -0600

Just to clarify, I was not in any way using the Microsoft Word documentation as an example of anything even resembling ideal documentation. I was pointing out a flaw that has existed for at least ten years.

Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Website developer
Graphic Designer - Desktop Publisher - MS Office Expert
Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
Email: mike -at- writestarr -dot- com - Web:

----- Original Message -----

From: Janice Gelb <janice -dot- gelb -at- sun -dot- com>
Subject: Re: Documenting the user interface

Mike Starr wrote:
"Combs, Richard" <richard -dot- combs -at- Polycom -dot- com> wrote:

Every etc. needs to be explained, or users twist in the
wind? Nonsense.
That approach leads to at least two bad consequences:

-- Almost no one uses that 400-page manual because they
get sick of wading through useless information like
"The First Name field is where you enter the user's
first, or given, name. The maximum length is 30
characters. The valid characters are the letters
a through z, A through Z, ..."

I don't want to speak for Richard but I doubt
that he's saying that non-intuitive fields
should never be mentioned. I don't think you
can compare options about line spacing to a
self-evident field like First Name. There's

(And, btw, I wouldn't use Word Help as an example
of ideal documentation. The few times I've had to
use it, I've found that they are usually ok about
telling you what option you need to accomplish
something but they rarely tell you where to find
the $#*(@ thing!)

-- Janice

Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address


WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!

Create HTML or Microsoft Word content and convert to Help file formats or printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -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.

Previous by Author: RE: Documenting the user interface
Next by Author: Re: Approach for user manual
Previous by Thread: Re: Documenting the user interface
Next by Thread: Release notes, customer support and product managers

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

Sponsored Ads