atw: Re: Version management details in a document

Bob Trussler:
You wrote:
> I am at a site were we are developing document standards, with accompanying 
> templates.
> The work we do is designing, building and maintaining large computer systems.
> The programmers (developers) are used to noting every program change in a 
> table at the
> start of the program.
>
<snip>   etc...


And Another Thing!

As I understand it, the longer term justification for maintaining doc change 
details etc is to maintain productivity, which in some (worrying, but generally 
infrequent) circumstances can certainly be degraded by having someone relying 
on an out of date document etc.  This is fine, until it turns out that the 
amount of work automatically implied by insisting on the kind of record-keeping 
referred to probably finishes up losing more productivity that the evil you're 
trying to avoid.   And that's before we find everyone sitting around (as in 
this case, presumably) arguing about where the details should go etc etc.... 
a.k.a.: disputing the number of angels that can dance on the head of a pin.

If a doc control system isn't in place to put all this minor detail away 
safely, at least there's a convention of separate release notes in most 
workplaces.   With a new software release, I don't expect and don't want to 
have a GUI display cluttered up with 5000 notes on code changes etc.....  If I 
want that stuff,  if I'm an internal developer, I look to the version control 
system, and if I'm an outside user, I look to the release notes.
Why should documentation meant to be read by humans looking for basic 
understanding have their vision clouded by such details?   Just stick the doc 
change details in release notes, too.


-PeterM
peterm_5@xxxxxxxxxxxxxx
Everybody is somebody else's weirdo. - Dykstra
**************************************************
To view the austechwriter archives, go to 
www.freelists.org/archives/austechwriter

To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxx with 
"unsubscribe" in the Subject field (without quotes).

To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go 
to www.freelists.org/list/austechwriter

To contact the list administrator, send a message to 
austechwriter-admins@xxxxxxxxxxxxx
**************************************************

Other related posts: