Subject: RE: levels of detail -- are we beyond this?

Subject: Subject: RE: levels of detail -- are we beyond this?
From: "Peter Gold" <peter -at- knowhowpro -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sat, 16 Aug 2008 08:50:43 -0500

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

>> Tom Johnson wrote:

>> I just ran into some detailed instructions on going to a website that
>> like this:
>> 1. Open Internet Explorer by clicking *Start* > *Programs* >
>> Explorer*.
>> 2. In the *Address* field, enter ** and press
>> *Enter*.
>> Is it me, or is this kind of detail totally unnecessary in this day
>> age?
>> I'd say 99% of the time, people will understand the much simpler
>> "1. Go to";

> Let me be the first to say both "It Depends" and "Know Your Audience."
> :-)

> That said, unless the doc is _clearly_ aimed at the novice computer
> user, this level of detail is not just unnecessary, it's positively
> _harmful_. The reader who's owned a computer for more than three days
> will be put off and will either stop reading completely or will start
> skimming disinterestedly, half-heartedly looking for the useful parts,
> and will be more likely to miss something important.


These are good arguments for interactive electronic documentation and
help that enables users to adjust the level of provided detail to suit
their needs at any point. This requires that the documentation, help,
and UI are developed with this adjustability. And, yes, the UI should
have a permanent on-screen mechanism to adjust the level that
beginners can't miss seeing. Instructions for hiding this prompt
should be advanced enough that only experts could execute it.

In the old WordStar-era days, it was not uncommon for software
application interfaces and help to offer Novice and Expert prompting


Peter Gold
KnowHow ProServices

ComponentOne Doc-To-Help gives you everything you need to author and
publish quality Help, Web, and print content. Perfect for technical
authors, developers, and policy writers. Download a FREE trial.

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.

Previous by Author: Re: FrameMaker 8: Table numbering reset after text inset?
Next by Author: RE: How did you get started in tech writing?
Previous by Thread: Re: TECHWR-L Digest, Vol 34, Issue 16: How did you get started in tech writing?
Next by Thread: Value added (or lost) by technical communication?

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

Sponsored Ads