RE: anyone else in the same boat? (LONG)

["Lydia Wong" <lydiaw -at- fpoint -dot- com>]

I agree with most of what Andrew wrote in his note with suggestions on how
to approach a new job as a new tech writer in response to "train2"'s query
to the list. My thoughts/suggestions that vary from Andrew's are
interspersed with his suggestions below:

> 1. Find the lead engineers.  Schedule meetings with them. Talk
> with them about
> the product. Get to know the products and what they expect of you.

I couldn't agree with this more. Add on to that, go to their product
meetings. You are a member of the team, so act like it. Go to those
meetings! Even better, try to listen in on their casual conversations.
You'll learn a LOT that way.

Also talk with the quality assurance staff. You and they often have the same
goals and the same requirements. If you can share tasks and help each other,
so much the better. We find ourselves sharing product specifications, notes,
and ideas with our quality assurance team members on a regular basis. They
are an invaluable resource (and we've found them to be excellent document
reviewers, too!).

> 2. Learn the products and technologies you will be documenting.
> Surf the net
> for information about your competitors. Get appropriate books on
> the technical
> topics.  For example, if your product uses Java, get a basic Java
> book.  This
> gives you a common language with the engineers, something
> considerably more
> valuable than a style guide.

Well, a style guide is a nice thing (more on that later). But in the long
term, yes, you'll need to understand the products and technologies you're
documenting. Do not feel that you have to become an expert immediately,
though. That can be way too intimidating. Start with a "Dummies" book for
now, and learn more as you go.

If I'd known how much I'd end up learning about programming and Visual Basic
when I started my current job, I'd have laughed in disbelief! But now I find
the knowledge invaluable.

There have been a lot of discussions on the listserv about how much
technical knowledge is useful, etc. I don't want to reopen that debate. But
I taught math for a while. I majored in math, and I found that knowledge was
put to good use when I taught. If I had kids, I'd want them to be taught
math by a teacher who majored in math, not someone who majored in education
and happened to take calculus. (Please don't flame me on this, folks. I'm
basing this on my experience, but of course, YMMV.) I believe it makes sense
that the more you know about the product you're documenting, the better you
can explain that product to others--which is the essence of what we do.

> 3. Read all the existing documents.

Definitely.

> 4. Start with a small, simple project first.  Make sure everybody
> knows what
> your responsibility is at the company. "I am the person writing
> all the docs."

Yes, it's good to make clear who's doing what. Don't be afraid to be
assertive about this (in a good way). You might find that folks who've been
writing documentation on the side are more than happy to have you do it. In
addition, you might find that this continues to enhance your knowledge of
the product.

For example, when I started at the company I'm at now, the tech support team
compiled the Read Me files and lists of bug fixes that accompanied releases.
That was all right, but they weren't always too well written, not
necessarily complete, and worst of all, we writers didn't find out about
some things we really needed to know to fix or add to the documentation.

Early on I suggested that we writers could write these documents, thus
making them consistent and complete, and we got the added bonus of getting
information we needed. The support staff didn't mind at all that they no
longer had to write those files. It was a win-win situation.

Also, not only start with a small project, but keep it simple. Sure, you can
create complex documents and elaborate help files, but they aren't really
necessary. Create complete, correct, concise, and clear simple documents and
help files, and add bells and whistles later.

> 5. Find out who will be reviewing your docs.  Ask them how they
> prefer to edit
> documents.  Conform to their wishes.

But if they've never had formal (or even casual) reviews of docs, they might
not know what they want. If that's the case, try to establish a simple, but
clear system. I've been fortunate to work with developers who provide very
helpful reviews, but just like any of us, they like to understand what's
expected of them. If the whole process is new to them (and you), set up a
simple process that works for the team and for you, then document it, and be
sure to provide clear instructions to the team. They won't follow all of
them, but if they know what you expect, and they're generally helpful folks
(which most people are, really), they'll do their best to help you.

>
> 6. Be humble, be respectful, and accept criticism.  Do not fall
> in love with
> your words. Do not throw a tantrum when the engineers reject your
> first work.
> You have to please them as much as you have to please the readers.

All true. Very true. Remember that you're on a team with these people, and
the product, including the documentation, is a team effort. If part of the
team isn't pleased, then something needs to be addressed. Also, remember
that in time you'll probably have helpful comments and suggestions
concerning their work (after you know more about it, of course). If you can
accept criticism gracefully, you've set up a good model for them to accept
your suggestions just as gracefully.

> 7. Produce results quickly.  Prove yourself capable.

Always good advice. ; )

> DO NOT...
>
> 1. DO NOT Waste time with documentation plans, project plans,
> style guides, and
> other one-off work.  This is a tremendous waste of time and
> energy.  You need
> to prove your value to the rest of the team right away.  Spending
> time writing
> documentation plans that NOBODY will read just makes you look like a
> work-shirking twit. Engineers do not care about your style guide. And your
> style guide does little to prove your writing capabilities. A
> lone writer at a
> company does not need style guides and project plans.  Do it all
> in your head.

In principal (and in my own work) I agree with this, but a few comments:

- No the engineers don't care about your style guide, but you as a writer
should. Don't spend a lot of time on this, though. Pick one, use it, and do
your work. If your company doesn't have one, pick one that works for you and
move on. (Chicago Manual is a popular choice, as is the Microsoft Manual of
Style, depending on your product and audience.) Style guides help us be
better writers, and someday when you get another writer, you'll have your
style decided. One less thing to worry about.

- Personally, I'm not big on creating a lot of planning documents. I don't
like to do them, have a hard time making myself do them, and don't see the
point. But I'm often working as the "lone" writer on a project, so I keep
information in my head.

However, I know some writers who need to document their plans, even if
they're working by themselves as the only writer on a project. They're good
writers, and they find that making charts, tables, and diagrams helps them
organize their thoughts. I find a good outline is my plan, usually. That
works for me, and the other works for them. If either system works for you,
great. Remember to take all this advice we're throwing at you and decide
what works for you. There are as many ways to approach writing as there are
writers.

> 2. DO NOT show up loaded for a battle. You must be accommodating
> to the other
> team members. You are here to help them, not the other way
> around. Find a way
> to work inside existing patterns first.  Showing up and demanding
> everybody
> start conforming to some arbitrary documentation process is a
> great way to get
> yourself ignored and shoved in a corner (and possibly fired).

More good advice.

> 3. DO NOT confuse the idealistic theories of books (like Ms.
> Hackos' book) with
> the harsh realities of everyday writing.  The world is not a well-ordered
> place. People resist change and order unless there is a clean
> path to success.
> If you are new and finding your footing the worst thing in the
> world you can do
> is start demanding some foreign process get implemented.  Produce
> results FIRST
> then you can build an empire.

Also true. You have time to read books on planning and management later.
Joann Hackos's book offers some good advice, but it is indeed offering
advice based on a well-ordered, ideal world. Pick up her book once you've
gained some experience with which you can put her advice into perspective.

<snip>

> Tech writers are judged by the outside world on their ability to
> *produce*
> insightful, useful, and technically accurate documents. Nobody in
> the outside
> world cares one tiny iota what style guide you used or what
> internationally
> recognized process you implemented.  Therefore, don't waste your
> time on these
> things.  Find a way to make the documents GOOD first. Then hone
> the process
> later.

Well, except for adding the comment that a good style guide that you adhere
to can HELP you create good documents, I agree with this, too.

Good luck, train2! I'm sure your current situation seems intimidating and
overwhelming sometimes, but you have a unique opportunity to learn and grow
as a technical writer. Relax, and try to enjoy the process of becoming a
technical writer. All of us had a first book and a first job, and we've all
made our share of mistakes. As long as you learn from them, you'll be in
good shape.

Lydia
__________________
Lydia Wong
Technical Writer
FarPoint Technologies, Inc.
www.fpoint.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.