"Bug" reporting for documentation?

[Bruce Byfield <bbyfield -at- axionet -dot- com>]

"Dawson McKnight" <dawson_mcknight -at- hotmail -dot- com> wrote:

>Am I crazy, or is this the bad idea that it smells like to me?  A few CRs 
>for a document I can handle, but to try to post all formal content changes 
>as "bugs" to be fixed, verified, and closed seems like overkill to me.  Does 
>anyone have any experience with this approach, not necessarily using 
StarTeam, but with some other source management tool, perhaps?

>I'm opposed to it because it is much easier just to embed comments within 
>the text of the document itself using Word's track changes function or the 
>equivalent.  You can't very easily track code and UI problems that way, 
>hence the need for bug reporting for software applications.

If you're the only writer, and you're very sure that you can keep
track of the changes, then you probably don't need versioning
software.

However, if you're one of several writers, plan to pass on the
documentation to someone else, or won't be revising immediately,
then versioning software can be very handy. Not only will it help
to ensure that mistakes don't slip through the cracks, but you
will have an entire history of the document, and can revert to an
earlier version if something goes wrong. With most versioning
software, too, you have tools that help you quickly compare
versions if you get confused. 

True, versioning software is more of a developer's tool than a
writer's, but don't be too quick to dismiss it.


-- 
Bruce Byfield, Outlaw Communications
Contributing Editor, Maximum Linux
bbyfield -at- axionet -dot- com | Tel: 604.421.7189

"And you've seen it before:
The names of good women and men,
Decreed by the sword and the pen
To be outlaws all over again."
-Karen Mathieson (Capercailie)