Re:Documenting the user interface

Subject: Re:Documenting the user interface
From: "Damien Braniff" <Damien -dot- Braniff -at- asg -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 12 Jan 2007 08:28:24 -0000

Interesting discussion and to me there's two situations - the real world
and the ideal world :-)

The documentation produced is the best that you can do following
user/task analysis (you know what's needed!) and whatever constraints
may apply that will modify what you know's needed! These include time,
money... all the usual suspects.

Everything is documented in a suitable hierarchy for the audience - most
likely to be used --> least. Relevant background material is provided
where appropriate and an excellent TOC/index to help the user quickly
find what they want. I've done this once or twice where the main manual
was a 'how to' manual with additional background info provided in
appendices. The Help provided screen help with pop-up for permissible
field values and links to background info that could be read (or not but
it was there!). I don't necessarily agree that you can have too much
info (though what's provided is always filtered) as long as it's well
structured and it's clear what's essential and what's 'additional'.

Sometimes though the audience takes over and there's no choice. At one
place I worked we were documenting a sonar system for the navy and the
User Manual was really a ref doc listing every feature, field etc.
Basically we were told that we couldn't tell them HOW to use it, only
what it could do!

At other times it's a matter of perception. We had a comprehensive User
Manual that scared the (non techie) users. When we looked at it users
were using a fraction of the features available regularly so we renamed
it as a Ref Manual and created a 20 basic user guide that could sit by
the PC and everyone was happy. Small, simple UG and they didn't mind a
large Ref doc as the very name implied you didn't need to know it, just
dip in occasionally!


Damien Braniff
Sr. Technical Writer
damienb -at- asg -dot- com

Waterfront Plaza
8, Lagan Bank Road
Belfast, N. Ireland BT1 3LR
Tel: +44 (0) 28.9072.3124
Fax: +44 (0) 28.9072.3324



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: Want to buy/borrow Peter Hartman book
Next by Author: Re: Tips for Getting Hired
Previous by Thread: Re: Documenting the user interface
Next by Thread: RE: Documenting the user interface

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

Sponsored Ads