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: An Engineer has infected my young mind! From:Sybille Sterk <sybille -at- wowfabgroovy -dot- net> To:"Sierra Godfrey" <kittenbreath -at- hotbot -dot- com>, "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 18 May 2000 23:26:31 +0100
Dear Sierra,
You are the technical author. You are the one writing the manual and you
know your audience. If the product is difficult to understand, then it
needs simple steps to lead the user in the right direction to understanding
the product. I entirely agree with you on that point. Our software is quite
complex and complicated, too, so I understand your problem quite well.
The engineer has no business telling you what to put into the manual. You
are not telling him what to put into the program, are you?
Anyway, how about a compromise? Create a User Guide which contains the most
important information the user needs to get started and the most commonly
performed tasks either just as step by step instructions or (in my opinion
preferable) in tutorial form. You can then add a reference manual that
contains every single bit of information the user could ever want to know
about with references to the relevant sections in the User Guide. This is
what we do, not because the engineers want us to, but because some of the
managers say our customers want this...
With this approach you should be able to make everyone happy. However, if
your boss is happy with the work you do, you should trust your own
judgement. Most engineers think that their programs are so easy to
understand that nobody really needs a manual anyway... There are,
unfortunately, very few programmers/engineers that understand that no
product can be sold successfully for any length of time if nobody knows
what to do with it or how to do this...
Good luck,
Sybille
At 20:26 18/05/00 , Sierra Godfrey wrote:
The engineer insists the manual should be presented as a reference manual,
with all the information there, and very little tutorial-style steps. I
disagree--the product is complex and difficult to understand.
I feel the only way a customer will be able to wade through it is to know
the necessary actions that must be performed to get it working and maitain
it, and follow short steps to achieve them.
The engineer feels manuals should be read two to three times over, because
the information is densse, and include all points. I disagree. There are
different types of readers, to be sure, but my readers will not know
anything about this product and will need a lifeboat--user-friendly, short
steps. Not all the information at once, which they won't know what to do with.
Sybille Sterk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Email: sybille -at- wowfabgroovy -dot- net
Web Site: www.wowfabgroovy.net
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"This writing business. Pencils and what-not.
Over-rated, if you ask me. Silly stuff. Nothing in it." -- Eeyore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
