RE: question on speedy collection of engr info

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

There has been some discussion on this list about it. In fact, a new
list has been started: the nettechwriters group
http://groups.yahoo.com/group/nettechwriters

Documenting the arguments to a command and information about that
command in an SDK is what I call reference material. 

To give you the nutshell version of my religious beliefs, I believe that
such reference material belongs in, or is, the source code and that's
where it should be maintained. 

I put specially flagged comments into the source code that the
developers and/or I maintain. A free off-the-shelf tool (Doxygen)
extracts these comments along with the actual prototypes into a
documentation system. I maintain the "how-to" information separately in
FM and merge them into the system later.

If you use the source code as your source, all you'd have to do is check
out the create CVS version and generate your reference doc's for that.
At the very least, you're prototypes would always be accurate.

The hard-part is playing ball with the developers and getting them to
trust you mucking with their code (comments). Another hard thing to
swallow is developers mucking with your descriptions. ... Ah, but
commented code is its own reward to engineering, as are accurate
prototypes to the SDK user. 

I'll be happy to give you details off-list.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com


> -----Original Message-----
> From: julie brodeur/mccready [mailto:jool -at- petting-zoo -dot- net]
> Sent: Thursday, September 06, 2001 1:03 PM
> To: TECHWR-L
> Subject: question on speedy collection of engr info
> 
> 
> 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.

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

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.