Re: User Manuals

Subject: Re: User Manuals
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 2 Jul 2009 12:17:34 -0700

My main rules are:

Make the content task-oriented (as opposed to UI-oriented or abstract).

Spend a lot of time up front getting the outline right. Usually this
means organizing the contents following a process workflow or
lifecycle. Look for user categories (e.g. end user, supervisor,
adminstrator) and iterative subprocesses (loops) that imply logical
TOC sections or levels.

Within the workflow outline, break the the content down into logical
modules. Start a logical group of modules with an overview that puts
them into the context of the workflow.

Put reference material at the back and cross-reference it from task topics.

Be comprehensive but concise.

Don't document the self-explanatory. To put it another way, don't
write uninformative "help" that simply narrates what the user is
looking at. When a programmer defines an unneeded context ID for a
self-explanatory UI element (such as a self-documenting wizard), link
it to a generally relvant topic, or the default topic.

Avoid redundancy by using cross-references.

Ensure accuracy by testing everything yourself.

Use graphics only when absolutely necessary. Compose screenshots
carefully to make a point.

Break the above rules as necessary, which shouldn't be too often.

On Thu, Jul 2, 2009 at 8:36 AM, LML<lleduc -at- designnettech -dot- com> wrote:
> Hi All,
> I've been researching around and looking at different types of user manuals
> and I'm wondering what you all think is the best approach for a useable
> manual. Can anyone point me toward any examples of great manuals, although
> such greatness may not be out there freely on the internet. I have found
> many bad examples and they are generally bad because even though the
> information is there, they are difficult to maneuver through.
> I'm working with Word right now and want to learn how to use Frame Maker,
> but I am not sure how quick of a learning process that will be (any input on
> that would also be appreciated).
> The manuals are distributed as PDFs or Flash documents and I know they are
> often printed out by the users, so that definitely has to be factored in.o

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

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.

Please move off-topic discussions to the Chat list, at:

User Manuals: From: LML

Previous by Author: Re: Edit PDF in Acrobat Pro?
Next by Author: Re: User Manuals
Previous by Thread: Re: User Manuals
Next by Thread: Re: User Manuals

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

Sponsored Ads