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.
As with any documentation, what goes in depends to a large extent on the
user and how well you know them!
To me a good user manual should comprise:
Introductory chapter: Tell the user up front WHAT it is, WHAT it does,
and HOW it's going to help them. This can be a few lines to several
pages to ... all depends on the audience and how familiar they are with
the product/type of product. Need to explain how this new all singing
all dancing product fits into the scheme of things and how it will make
their life so much easier. As John and others have said this is
bordering on marcom writing and can be simple/plain/flowery/whatever as
long as it gets the message across clearly.
Having told them WHAT it does I'd then describe how the manual is
structured:
Chap 1: This intro...
Chap 2: Feature 1 - WHAT it does and HOW to do it
etc
In that first chapter you've then told them what it is, what it does,
and provided pointers on where to find the relevant HOW bits that
they'll come looking for. Couple that with a good TOC and comprehensive
index and you're well on your way. If you like, it's (using the novel
metaphor) a bit like the blurb on the back of a novel that gives you a
'taster' that may/may not tempt you to read it.
I tend to provide a brief overview at the start of each chap plus,
depending on the chap size, a mini-TOC to help the user quickly find the
info they need.
Damien Braniff | Technical Writer
damienb -at- asg -dot- com
Technical Communications
ASG | asg.com
Waterfront Plaza
8, Lagan Bank Road,
Belfast, N. Ireland BT1 3LR
Tel: +44 (0) 28.9072.3124
Fax: +44 (0) 28.9072.3324
End-to-End Technology Management
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! http://www.webworks.com/techwr-l
Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
