Re: question on speedy collection of engr info

["Eric J. Ray (remote)" <ejray -at- raycomm -dot- com>]

On Thu, 6 Sep 2001, julie brodeur/mccready wrote:
> I'm currently documenting a toolkit with a large number of commands, which
> the engineer changes often during point rollouts. So my doc is *always*
> way out of date by the time I learn of the changes and talk to QA -- both
> QA and Engr get confused on which change affects which release, despite my
> best efforts at asking pointed questions and pinning down the exact usage
> for the upcoming release. The confusion comes, of course, because there
> are so many of these commands and minute changes in them to track and
> juggle.
>
> So anyway, I need to figure out how best to keep track of this all and
> draw some line around which things I document for which release, and how
> that will ultimately help the people reading the doc.
>
> Any tips are appreciated.
>
> Some things I've thought of:
>
> * trying to get the engineer to add a short message to his CVS check-ins,
> and setting up an auto email to me on his check-ins

This is VERY good--bordering on essential. Even if the
message isn't there, at least you know _something_ changed.
You mention below that there's a bugdb. It's quite helpful
to have the putbacks associated with a specific bugid
or formal RFE...and those usually provide all the added
information you need.

> * meeting with the engineer more often (difficult, because he's generally
> out of the office and kinda flaky about making meetings anyway)

In this case, I wouldn't try to meet about all of the issues.
I would make SURE that the engineer really understands the
impact that his/her putbacks have on you, and ask for suggestions
for managing and synchronizing the process. If you mention
your bullet point below as something you're trying to avoid,
you're almost guaranteed cooperation. ;-)

> * breaking up the toolkit guide into portions and emailing the engineer
> what i have in bite-size chunks, hoping he'll review it and send me
> comments

The only value I'd see in this approach is as a carrot/club
to help the engineer get interested in a good solution. You're
unlikely to get good information this way.


> * doing the above, but using the bugdb instead of an email

That's pretty good, depending on how your organization uses
the bugdb. (I've seen it as a tracking tool, which is good
and appropriate for this situation, or as a club/evaluation
tool, in which case this approach could burn bridges pretty
quickly.

>
> * trying to get QA person to warn me a couple days before he plans to test
> the new commands so I can pester the engr for exact usage before QA tests
> it

You need to get into the same information loop that the QA
person is in. If the QA person can schedule testing for new
commands that you don't know about, then the QA person has better
information than you do. Find out where that info comes from,
and use it as a baseline.

> * trying to get some manager types to realize that a ton of tiny point
> releases aren't as helpful as they might seem

Aha! Fixing the root cause, not the symptoms. Good idea.
You could just document the major/minor releases, and let the
point ones go with release notes (or less). If you need
management support for that, document how much time/effort
(yours, engineering's, QA's, etc) each point release causes.
IF you have access to customer info, you could probably come
up with something like 1 hour of development/engineering time
per customer to use a given point release. That's weighty.

Good luck,
Eric



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.