Re: Opinions please

["Marcia L. Whitmore" <whitmore8 -at- AOL -dot- COM>]

Here are the most important guidelines I've picked up in my 8+ years in the
field. Some of these may be repeating previous themes, but I suppose it
doesn't hurt to emphasize important points.

There will always be ways to clarify and simplify what you have written. Keep
looking for them.

Know your audience.

Over-explaining can be as bad as under-explaining.

Learn to break information out under meaningful headings.

Take the time to include meaningful illustrations and tables to get a point
across.

Never claim to know more than you know. This will get you in trouble.

Learn to direct subject matter experts gently toward what you need to know.
Some people are overly helpful and will gladly take too much of your time and
their own explaining a subject, but they may never get to the points you need
to know. A list of directed questions prepared in advance helps with this.

Compare answers you receive from different technical experts or reviewers and
make sure that you resolve any conflicts. Bring the experts together if
necessary.

Learn to love reviewers who give you lots of comments rather than the ones
who give you very few. Constant feedback is the key to success.

Get to know the people in your organization who have direct contact with your
customers or readership. Their suggestions will be invaluable. If possible,
make contact with customers yourself and learn what they value and dislike
about your documentation.

If you are writing procedures, always validate your work and have someone
else validate it as well. Nothing is perfect the first (second, third,
fourth...) time.

Constantly report problems and suggested solutions to your managers in a form
that they can deal with. Never be afraid to ask for an opinion or assistance.

As a technical writer, you will always be part of a team. Learn how you can
work best within the team. And don't stick solely to your desk. Participate,
interview, share knowledge, listen to technical discussions, read information
about your products, and ask lots of questions. Go to trade shows and related
conferences if you can.

Seek the balance between respecting experience and finding out how things
work for yourself. There is one!

Marcia Whitmore
Publications Manager
InterCon Systems
Herndon, VA
marcia -at- intercon -dot- com
whitmore8 -at- aol -dot- com

I always try to speak for myself. If you want to know what my boss thinks,
ask him!