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

[Candace Bamber <cbamber -at- CASTEK -dot- COM>]

Hi Melissa,

I haven't met a piece of software yet that *didn't* change during
the development process. And I haven't met a development organization
yet whose first thought was to notify the documentation folks that they
just made a change.

     >You 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?

Maybe look into how the developers who are making the changes are
notified. In my current and last company there are three ways:

1. Developer Bulletins are issued by Development Manager to reflect
changes in anything effecting the way the software is coded

2. Problem Log is a database that contains anything the testers find or
that the clients want changed.

3. Review Meetings (for design or developed software). You don't have to
go to all of them, but you should be on the mailing list so you can show up
if you need to.

If any of these things (or their equivalents) exist in your company,
you should have access to them. Tell whoever "owns" them that by being on
the list you won't have to bug the developers all the time to find out
what's going on.

     >I know I should be more proactive and involved with the
     >developers...

Yes - I think this is not optional - it's simply part of the job and we
have
to do it whether or not it's particularly convenient (it's not one of my
favourite parts of the job!). In my last job, we had all three of
the above "procedures" and changes were made all the time that were not
officially recorded. (I can't speak for my current job - I'm still learning
the ropes)

I solved this by using the bottom up "critical mass method for change"
rather than banging my head against the wall of uncooperative management.
I went to the developers one at a time and told them exactly what the
problem was and asked for their help.  I told them that I really wanted
to represent their hard work accurately in the book. NOT A SINGLE ONE
realized that making a change impacted on my work. Nor did they realize
HOW MUCH impact. None of them realized that a quick change to a screen
could mean a couple hours of changes to me.

They agreed, painfully, one at a time, to put me on their mailing lists
and send me "I made a change; have a look at blah" emails (which I would
then have to follow up). With frequent reminders, about 75% actually
got the habit of doing it. It wasn't perfect, but it served.

And when upper management asked how things were going, I told them how
great
the development organization was - how responsive and efficient. The
development
managers who weren't willing to help me out were quite willing to take the
credit for a job well done. In the longer run, upper management started to
expect the development group to be responsive and efficient and put the
necessary pressure on the development group....

My dollar's worth...

Candace
cbamber -at- castek -dot- com




***************************************************************************
*********************************************
Candace Bamber

now thankfully at:            "Whatever you can do or dream,
Castek Software Factory    Begin it.
Toronto, ON, Canada                 Boldness has  genius,  magic and power in
it."
416-777-2550 X 331                      --- Goethe
***************************************************************************
*********************************************

 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