TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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 :-)
REAL 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.
IDEAL WORLD
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
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! http://www.webworks.com/techwr-l
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. http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
