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: Help a newbie tech writer? From:"Bruce H. Johnson" <corpknow -at- EARTHLINK -dot- NET> Date:Wed, 12 Jun 1996 06:22:44 -0700
>Date: Tue, 11 Jun 1996 23:28:24 -0400
>From: Raymond Chenier <rchenier -at- SYNAPSE -dot- NET>
>... as my first job, I will be the first and only writer at a company that
designs software applications and trains people.
>My first tech writing task involves designing a software manual to be used
by engineers. I will also be redesigning and implementing their WWW
site.
...
>I have interviewed engineers and have had a quick glance at the software in
question. I find myself yearning to know what types of sections would
work
well in a manual of this type. The users will be engineers, some who are
using the app and some who have never used it. It seems this manual is
to be
more of a background and concept type document, rather than an
instruction
based manual.
>I am only at the audience analysis stage so I'm probably trying to jumpahead. This project should turn out to be a great challenge and with the
help of STC Members and this list I feel confident in my ability to
produce
a quality technical document.
--------------------
You've got a good start, identifying the audience. Are the engineers
your company engineers, or "engineers" from outside? Nail that down
pretty well.
As for content, especially if the manual is mainly internal, get the
vital data down somewhere, even if it isn't immediately published.
"Vital" data is the stuff in the engineers head that isn't documented
anywhere (or poorly documented). If Engineer X got hit by a Mack truck
tomorrow, what information existing solely in his head would be lost?
Manuals of this nature are alive; they change. The 20/80 rule says that
20% of the existing information will usually handle 80% of the
situations. You and the engineers have to evaluate what that 20% is. If
you try for 100%, you'll never be published and it will never be right.
A few passes of the 20/80, and you'll have what you need.
You have to evaluate what is important in relation to everything else.
That comes from interviews with the users and engineers. What are the
common questions the Help Desk gets, etc. Look around at some of the
FAQs on various subjects.
HTH
--
Bruce H. Johnson
Corporate Knowledge, Inc. -- Your knowledge transfer specialists.
corpknow -at- earthlink -dot- net Los Angeles, California
#include <disclaimer.h> http://www.business1.com/cki/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner: ejray -at- ionet -dot- net
