Starting a documentation department?

Subject: Starting a documentation department?
From: "Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Fri, 5 Nov 1999 08:52:59 -0500

Stepheni Norton feels that <<... we need to get things set up for a
'documentation department' ...it's easier to set up standards in the
small stages than when we grow. I have a lot of good ideas, but
would like to follow a 'preset plan'>>

Excellent idea. The first and best thing you can do is to formalize a
friendly and mutually respectful working relationship with your
partners in crime <g> (i.e., the colleagues who actually build the
products you document). The better the relationship, the easier it is
for you to keep up with changes to the products and to have
access to the people who can answer your questions. And
although relationships have to be built from the ground up (they're
_human_ relationships, after all), it helps if you've got management
support for the notion that you and the developers are both equal
members of a team. Once that notion of ongoing cooperation
becomes part of the corporate culture (the unwritten rules for the
way things really work), it can become permanent if you're willing
to work to keep the relationship going. That'll make everything else
you do enormously easier.

Along with building the relationship, you need to build a review and
revision process into the new department. Work with your
colleagues to develop a process that works for all of you; there'll be
some compromising involved, but that's an important part of the
process. There'll also be ongoing revision of the process until you
take the theoretical process you developed in a meeting and adapt
it to all the inconvenient realities of daily life in your workplace. In
the end, you'll have a process that everyone (including the clients
who benefit from well-reviewed docs) can live with. And to
acknowledge Andrew Plato formally: Make that process flexible!!!
The more restrictive the process, the more stifling it becomes and
the less likely people are to use it.

Finish up by developing a style guide everyone can live with and
that helps everyone get their job done rather than simply imposing
dead, static standards. Have a look through the techwr-l archives
for discussions of "style guides" and you'll get all kinds of
information on how you can create something people can actually
use. I'm currently working on an article for _Intercom_ that expands
on many of my previous comments (including some in the past few
weeks) and explains how you can make a style guide dynamic:
that is, turn it into part of the workflow and something that makes
the work easier, rather than simply creating a dusty book that sits
on a bookshelf and becomes something that nobody other than the
editor ever uses. The article isn't ready for prime time just yet, but
hopefully it'll appear in _Intercom_ in a few months.


--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"If you can't explain it to an 8-year-old, you don't understand it"--Albert Einstein




Previous by Author: Newbie in Houston?
Next by Author: Naming tabs in dialog boxes?
Previous by Thread: Re: techwr-l digest: November 04, 1999
Next by Thread: Q: Managing one set of help files for multiple products


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


Sponsored Ads