Re: Is it just me? S/W doc question

[Paul Branchaud <paul -at- VEDGE -dot- COM>]

On Thu, 29 May 1997, Melissa Hunter-Kilmer wrote:

> When you're documenting an application, and it changes, is there
> a procedure in place to notify all concerned?  Or do you just
> find out after you've written the chapter, and then you have to
> rewrite it?

Melissa,

The short answer (based on my experience) is Yes to both questions.

[slow dissolve from the present to that wild and wacky year, 1992]

The first company I worked for had little to no communication between the
developers and the writers. A clear "us & them" mentality. Many times, we
were kept so in the dark about changes to the interface that we only
discovered it after we had sent a master copy to the print shop! It was
just like in the movies: running breathless to the print shop and yelling
"Stop the presses!" ;) Much of the problem revolved around the fact that
each developer kept a copy of his/her changes to the interface on their
machine and didn't include it into the "official" product directory until
they had debugged their code. There was the added fact that we only had
two or three "testing" stations with the updated software was available
and you almost had to schedule time to find out what had changed. After a
particularily massive change that affected a whole chapter (with little
time to make the changes), the doc team had a nice looooong chat with the
developers which resulted in our being kept a bit more up to date on
upcoming changes, but we still found some out at the last minute.

[Scooby-Doo wiggle dissolve to my current workplace]

One of the first things I discovered when working at Visual Edge, is the
use of mailing lists to distribute notices of changes to the product.
"Where have you been all my working life?" This was the greatest thing
since sliced bread! A "Code Change Report" for each product line. It was
so simple! :) Any change that gets implemented into the main code that
gets compiled daily, MUST be documented. The report is redistributed to
all who are on the mailing list (this includes the writers), so they are
aware of the product change. No change is too minute; something as
seemingly trivial as a date change for a copyright notice on a
splashscreen is reported. Since paper docs are not compiled as part of the
product, we do not have to notify the group of the changes. However,
online help and HTML-formatted documents are compiled as part of the
product, and changes to these documents must be reported to the group. As
wonderful as this sounds, it can be daunting to return from a week's
vacation to find 125 code change reports in your mailbox, only to discover
that maybe 3 affect you in any way (the *last* 3!). Documentation of all
the product's minutia can be tiresome, but nobody can say you weren't
informed!

> relationships that their managers frown on.  It is one of my
> ongoing, unwritten tasks to help these managers understand the
> importance of good doc -- that is, they don't get it, so they
> deliberately keep tech writers out of the loop so that we won't
> take too much time with the developers.

Perhaps suggest to all managers involved to implement a database/mailing
list where all product changes are recorded. This way, you are kept
abreast of product changes, the "unclear on the concept" managers won't
have to beat you off their precious developers with a stick, and there is
a repository of product changes that can be used to track product
revisions. It seems to be the solution you are looking for.

Or am I the only one who feels this way?

[fade to black, roll credits]

Paul
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
Paul Branchaud                  "Men, do you fear that, one day, your
paul -at- vedge -dot- com                   wife will run her hands through your
Technical Writer                 hair... and you won't be there?!"
Visual Edge Software, Ltd.             -- Richard Jeni (on hair loss)
--My opinions are rarely shared by Visual Edge and other smart folks--

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html