atw: Re: Version management details in a document
- From: Peter Martin <peterm_5@xxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>, <austechwriter@xxxxxxxxxxxxx>
- Date: Tue, 30 Jun 2009 15:13:06 +1000
Bob Trussler:
You wrote:
> Thanks for the comments so far.
> Just a note to explain a few issues.
>
> "...it simply shouldn't be there"
> My users request it and they DO read it.
>
> " ... be kept for lookup in a separate version control system of some kind"
> These
> docs are often a printed version of a specification, and the developers
> really do check
> the version details, so having them noted in the document is handy to both
> write and
> find. It also mirrors what they note when they get coding.
>
> I am struggling to get them to write anything, so it has to be really easy and
> convenient.
>
> "Get a life !"
> Did I mention that the users here are programmers.
>
> "... who is there that wants this stuff that can't find it in a doc change
> audit trail
> ?"
>
> Did I mention that the users here are programmers.
>
> "Unless I've misunderstood, this isn't at all the same as routine history /
> version
> records of routine documents that civilians use"
> Correct, the users here are programmers.
>
> These programmers do have a system where they check out a program to update or
> whatever, so the version notes in the code header block (title page
> equivalent) are
> minimal. The code library maintains the audit trail.
>
> The version control notes are within specifications, requirements, designs,
> and so on.
>
> Bob Trussler
Oops. Sorry. Thought we were talking about human readers for a while
there.....
So you've got these live creatures who actually read version details of specs
inch by inch.... Shheeesh !
You're kidding, right ?
Meanwhile, I've seen details of this kind quite comfortably handled in a series
of different environments, using bug tracking, version control and combinations
thereof, including documentation kept in parallel with code within the version
control system.
When you change a document, you make a change / bug entry. When you check it
into the version control system, it gets a version number. If you want to, you
can link that to the current code version, the bug record and/or whatever. Or
you can maintain doc version numbers that link to the bug-tracking database
records. Whatever.
What else could they want ? You track the two in a synchronised system.
Change entries get listed in all kinds of weird and wonderful ways, and you get
the advantages of being able to sort your details on different keys etc etc.. .
Static docs tables don't do that. They give you static keys.
Takes a bit of attitude and methodology change to get it going... but then, if
you're talking about programmers...
Er they do track bugs, right ? Oops. Yep... Programmers. You said that.
Nah. Give em hell. Keep doing it their way.
-PeterM
peterm_5@xxxxxxxxxxxxxx
I like a man who grins when he fights. - Winston Churchill
**************************************************
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:
