atw: Re: Version management details in a document
- From: Peter Martin <peterm_5@xxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>, <austechwriter@xxxxxxxxxxxxx>
- Date: Tue, 30 Jun 2009 12:55:47 +1000
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:
