Re: Setting Doc Requirements for Developers

["Marshall, Elizabeth" <BMarshall -at- WCOM -dot- NET>]

> I think doing a little internal marketing/PR is very important. I
> constantly stress to developers that if they share information with
> me,
> I can make their job easier.  Listen for those moments when the
> developers complain about someone who just called with what they think
> was an easy question (and kept them on the phone for an hour) and
> remind
> them that if they let you know about these phone calls you can address
> the topics in the next release or with a handout they can fax to the
> caller (which gets incorporated into the next release).
>
> I am currently in the process of instituting not only a document
> request
> form and a document release form, but a standard for documentation
> project plans.
> *     The document request form asks the key contact(not always the
> developer) to list the specific objectives of the documentation.  If
> they say "we just need documentation."  I sit down with them
> one-on-one
> to clarify what documentation can do for them.
> *     The document release form requires them to read the document and
> sign their name that they approve it.  It allows them to make
> suggestions, corrections, and additions. But it also helps the
> developers realize that they are partly responsible for the quality of
> the documentation. If they think its missing information but don't say
> anything until it is too late, it isn't my fault and I remind them of
> that.  The newest feature to this form is a schedule for reviewing
> published documentation.  In your case, you might have the developer
> agree that whenever a new release is distributed the documentation has
> to be reviewed first before the software can be release. (When they
> are
> forced to put documentation into every software release plan they
> start
> planning ahead.)
> *     The documentation project plan explains to the non-writer (the
> developer) how documentation projects work. This isn't just a plan
> that
> I write so that my boss knows what I am doing but it is an agreement
> between me and the key contact to work together. It clearly outlines
> what my responsibilities are and what their responsibilities are and
> what kind of turn-around time we both require to be success in our
> jobs.
>
> Having said that.  The only way to get the developers to agree to that
> is by making them realize how much time good documentation can save
> them.  One way to do this is, to have someone (a help desk or the
> developer) keep a list of all the calls that come in about the new
> release for the first week.  You write an interim documentation that
> answers those calls and distribute it to everyone who received the
> product release.  See how many less calls you get the second week.  I
> have conducted this experiment with several developers and the result
> has always been an improved relationship/respect with the developers.
>
>
> > -----Original Message-----
> > From:       Eric J. Ray [SMTP:ejray -at- RAYCOMM -dot- COM]
> > Sent:       Tuesday, August 11, 1998 3:53 PM
> > To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> > Subject:    FWD: Setting Doc Requirements for Developers
> >
> > Name withheld upon request. Please reply on list.
> >
> > *************************************************
> >
> > For the next rev, I want to provide the entire team with a couple of
> > things:
> >
> > * A clear understanding of my role and responsibilities
> > * An understanding of the type of info they should be passing on to
> me
> > * An understanding of what I can bring to the team
> > * A matrix of how their level of communication effects the quality
> of
> > the
> > doc I can provide
> >
> > Pretty much, I have to teach them how to work with me.
> >
> > My boss wants to sit down later this week to discuss this. As their
> > are
> > another twelve writers, I am a guinea pig for showing how valuable
> the
> > writer can be to creating a quality product and doc.
> >
> > I need help from you with how you have dealt with issues like this
> in
> > the
> > past.
> >
> >


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