Re: communication with programmers

[Stina Lane-Cummings <stina -at- REAL -dot- COM>]

Archie Ziviello wrote:

<<...I'm documenting a VAST mainframe system under development.... It seems
during implementation we have significant amounts of interface design
change which determines exactly how the user is supported in the
job....What kinds of project management are YOU involved with?  How do you
manage your effort when there is no clear expectation of you other than "to
write the manual.">>

It seems to me the source of the problem isn't the programmers, but that
"there is no clear expectation of you other than 'to write the manual.'"  I
suggest you do a marketing job on the people you work with--probably
managers, not programmers--of what this next manual is going to look like.
They need a carrot:  "Your feature will be described in all its glory" and
a stick "...but if I don't get information from you by August 31 I can't
describe it at all, because I will be writing about someone else's
features."

In my department there is a program manager responsible for each set of
features. These managers are supposed to create specifications which are
checked in to a version control system. For every feature, I created a
brief outline of how I would document the feature. I listed significant
aspects of the feature, typical user tasks, and so on. And I included a
section summarizing the ideal documentation and the absolute minimum we
could get away with--including "no mention of this feature in the manual
anywhere."

I met with each manager to make sure they agreed with my outline and
understood it. While I was meeting with them, I explained what could make
the plan fail, and that I would be coming to them later for complete
information once the features were ready. Then I added the outline to the
official specifications. My outlines were pretty sketchy at first, but the
more I did, the better I got. (If no specification existed for a feature I
knew darn well was supposed to go in the product, I still added my outline,
but all it said was "This feature will not be documented.")

I spent a lot of time on these outlines--time I used to spend writing then
erasing--and it was well worth it in the end. When the features were
finally stabilized enough for me to write about them, my outlines were
ready. Program managers saw the documentation plans as official work, and
saw themselves as being responsible for providing me with information. I
deal with them for the big picture and scheduling issues, and I go to the
programmers only for technical information. I don't know about you, but I'd
much rather hear "Feature X is going to change next week, I'll let you
know" rather than "Oh, didn't you know that Feature X had changed?" The
former is what you can get from program managers, the latter from
programmers.

Good luck,
Stina Lane-Cummings
Technical Writer
RealNetworks, Inc.

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=