Starting a documentation department?

["Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>]

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