RE: Documentation planning (was Re: FW: Extreme Technical Writing ) long

Subject: RE: Documentation planning (was Re: FW: Extreme Technical Writing ) long
From: Sean Hower <hokumhome -at- freehomepage -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 11 Jan 2002 13:30:06 -0800 (PST)

I don't know if this is relevant, but I thought it would
be interesting as a case study for you. I didn't know if it
was appropriate for posting on techwr-l so I'm just sending it to you.

My first job was in an environment much like the one you
described, but worse. I was a mere writer but watched as my
manager jumped through so many hoops I got motion sickness.
My manager was an experienced technical writer but had never
managed a technical writing department before. He had been a
captain in the MPs though.

The first problem we had was convincing everyone that
documentation was a necessary part of the equation and that
it took more than just a few days to write good
documentation. We were documenting a suite of programs (6 in
all) plus a pretty hefty junk of hardware. The original
document set was only about 50 pages for the entire setup and
was from V1 while the current version of the software was V4.
Still, many managers thought the docs were just fine, despite
the fact that most people who used the product always
complained about them.

There was no structure in the company, just a vague
perception of who the bosses were and a definite knowledge of
who the uber-bosses were. So, when we started documenting the
product, we had to create a structure for the department. My
first role was to assemble guidelines. They covered simple
things like when to use bolds and underlines. We all worked
together to come up with the template we would use. This was
loosely based on past experience and formats we liked from
other manuals. We also developed the document structure, file
structure and editing cycles. We ended up deciding on a
round-robin type editing style where everyone was both editor
and writer. It worked pretty well. We also had to establish
guidelines for the SMEs because once they were convinced that
doucmentation was needed, they were also convinced they could
write it better. We had signoffs to keep track of which SMEs
had read and commented on the docs. We also had formal and
informal reviews at important milestones. Eventually, we
brought in some of our users to review the docs for
usability. We kept everything, including small email
transactions, to show our progress. The paper trail was also
used to prove that certain people had or had not done
something. This did and did not work because in most
instances the bosses had had their underlings do the
signoffs. On several occassions people were fired for no
reason other than the fact that their bosses made mistakes.

All the structure began to worry the other bosses and even
the uber-bosses. We had to somehow make them feel like they
were part of the process in order for them to provide us with
the resources we needed to get our jobs done. If we didn't do
that, they would ignore requests to complete reviews or make
their underlings unavailable for us to talk to. This was a
difficult negotiation that took place on several levels and
over a long period of time. These negotiations were easiest
on the "grunt" level and became more difficult as you had to
deal with people in the higher ranks.

When all was said and done, we completed an 8 volume set that
was around 2000 pages. A far cry from the 50 pages of the
original documentation. Once the job was done, several people
were fired or quit. I'm working somewhere else now, and the
original team that numbered as high as 8 people is now down
to 1. The processes we had put in place are not followed any
more. Things are pretty much back to the way they were before
we had attempted to establish the department.

I use this experience as a valuable educational tool about
what to do and what not to do when you enter a company or
start up a docs team. It also gave me a schema to use to
recognize bad situations. It also highlighted the amount of
politics that can go on in a company and the need to play
those politics in order to get your work done.

Sean Hower

technical writer

Get 20MB of free web space now at

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for?

Have you looked at the new content on TECHWR-L lately?
See and check it out.

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 for more resources and info.

Previous by Author: Re: Local Networking
Next by Author: re: Styles: To Base or Not To Base
Previous by Thread: Re: Mailto: frame to PDF
Next by Thread: Robohelp best alternative?

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

Sponsored Ads

Sponsored Ads