Re: Help a newbie tech writer?

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 11:28 PM 6/11/96 -0400, you wrote:
>Hi:

>As a recent graduate of a tech writer program and a new employee at an
>engineering firm, I hope to be able to get answers to some questions. You
>see, as my first job, I will be the first and only writer at a company that
>designs software applications and trains people.


Don't feel bad; many of us are in that position, although it's a harsh way
for a beginner to get started. Your major problem at this point is perspective.

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

>Has anyone ever done one-on-one email mentoring? I just made that up, so has
>anyone ever heard of it? Is it something someone would consider doing? Or is
>one better off carefully asking the right questions directly to the list?

I've never heard of it, but your best approach might be to post specific
questions here.


>I will be receiving mentoring of sorts through fellow STC Members in my
>area. I thought getting additional help from someone on this list, or simply
>from the list, would also be very beneficial. I have been studying JoANN
>Hackos' "Managing Your Documentation Projects" for about three weeks and
>find it extremely helpful. However, I don't have a book entitled: "So your a
>new tech writer with no experience on your first project." :-)

Pardon me for asking, but why didn't your tech doc program in school give
you some hard-nosed experience in project development? I'd think that it
would be required.

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

Why is the manual a "background and concept type document"? That's usually
the province of third-party books or first-chapter introductions. Few
companies want to pay to disseminate concepts in expensive manuals. Is it
that the users are unfamiliar with the software functions, like clerks
learning Access? In that case, they need training materials, not a manual.

>I am only at the audience analysis stage so I'm probably trying to jump
>ahead. 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.

Audience analysis is the heart, soul and key to successful projects (success
measured by effectiveness in the hands of the intended reader/user).
Everything else follows after, and don't let your SMEs tell you otherwise.
You'll learn something right quick about your working environment...the
developers always think that 1)their products are too simple to warrant
task-based documentation and 2)gadgets are more important than people. Or
stated differently, documentation should stress fields, windows and forms,
because anyone with an IQ in double digits can run this stuff, and hey, the
really important stuff is the stuff we play with, you know? Resist this.
Perservere on your path. Always ask yourself first who the user will be and
what he will need to know. Then ask yourself what he already knows. The
delta, that difference, is your responsibility.

The next thing to do is to map the concepts in the document. Don't skip
this. Map out what you want to explain, then get it signed off. Sign off is
crucial, and not just the signature of your boss. Get your SMEs to sign off,
too. You'd be surprised how tractable and pleasant a SME can become if he
knows that his sig is going to appear in your files.

There's more, but that's the first week or so of the project. Feel free to
keep us posted on progress.

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support

Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.

http://www.iquest.net/simply/simplywritten

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