Re: Help a newbie tech writer?

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
>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
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
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
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.


Bruce H. Johnson
Corporate Knowledge, Inc. -- Your knowledge transfer specialists.
corpknow -at- earthlink -dot- net Los Angeles, California
#include <disclaimer.h>

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

Previous by Author: Re: Win95 Help questions
Next by Author: Re: Ventura to Online Help
Previous by Thread: Help a newbie tech writer?
Next by Thread: Re: Help a newbie tech writer?

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

Sponsored Ads