Re: Don Norman on Manual Writing

Subject: Re: Don Norman on Manual Writing
From: Bill Swallow <techcommdood -at- gmail -dot- com>
To: Jens Reineking <J -dot- Reineking -at- interkomelectronic -dot- de>
Date: Tue, 27 Dec 2005 10:24:27 -0500

Excellent topic! :-)

I agree for the most part. I'll focus on disagreements...

"The Manual Writers should be a part of the design team. Ideally, the
manual is written first, aimed at being short, simple, and
understandable. The designers and engineers help oversee the writing,
for when the manual is complete, it will serve as the product
specifications that they will follow. Therefore, they must buy into
the design from the beginning."

I was in agreement with the exception of writing the manual first and
having it be the specification. Writers should be a part of the design
team, and should influence the UX of the product. I believe that the
product specification is something very different, and should contain
much more info than a manual might. I also think that the manual can
only be conceptually complete before the product is developed. There
are specific processes that will need to be documented after the
features are implemented, given no design is perfect before
implementation... that is, processes will change with regard to UI,
even if the UX remains unchanged.

"Save the detailed control-by-control and menu-item by menu-item
explanations for the appendix."

In my experience, manual appendixes often become dumping grounds for
info, and become unusable (or avoided) very quickly. The detailed
info, for software, should be in the online help and be well indexed
and searchable. Perhaps it's not the context-sensitive topics, but the
info should be in there. Then again, if your audience loves paper, it
should be in the manual but in a logical section of the book and not
in the appendixes by default.

"Get rid of the lawyers, or at the least, put their required warnings
in a separate booklet or Appendix. When a manual is needed, it is
needed right away, and having to work one's way through umpteen pages
of legal warnings (that are behaviorally ineffective) only increases
the anxiety level and decreases the pleasure of the product. Page 1 of
the manual should tell how to do the most useful activity."

I saw this as opinion only. Legal info is a necessity in some cases,
and page 1 (in my own opinion) is best reserved for orienting the
reader and not jumping into the most useful activity... unless the
most useful activity is orienting the reader, in which case then I
agree. ;-)

On 12/27/05, Jens Reineking <J -dot- Reineking -at- interkomelectronic -dot- de> wrote:
> How To Write an Effective Manual
> by Don Norman
> Practical suggestion? Unreachable utopia?
> What's your opinion?

Bill Swallow
HATT List Owner
WWP-Users List Owner
I support Char James-Tanny for STC Secretary.

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release.

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 lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Don Norman on Manual Writing: From: Jens Reineking

Previous by Author: Re: Style guides?
Next by Author: Re: Don Norman on Manual Writing
Previous by Thread: Don Norman on Manual Writing
Next by Thread: Re: Don Norman on Manual Writing

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

Sponsored Ads