atw: Re: Version management details in a document

Ah, an oldie but a goodie. These are my personal preferences (and what I do 
when I get to set up the template):

Version number and date on front page. And every single page of the document, 
eg in the footer. I use field codes (though you have to make sure everyone 
working on the doc understands them).

Version history after the TOC. Because I hate having stuff before - it means 
you can't find the TOC (particularly with stuff that grows), and it's a 
legitimate part of the document, its existence should be recorded in the TOC. 
Incidentally, I quite often use a different numbering style for the "doc admin" 
headings like version history, approvals, etc - I use no numbers for them, so 
the "real" part of the doc starts with section 1. It's nice and easy with a 
couple of un-numbered heading styles based on their numbered counterparts, give 
them a level and add them to the TOC.

Version history not at the end of the document. I can understand the logic in 
putting it there, but then you have the "doc admin" stuff spread out around the 
document (unless all of it goes at the back) - and the other thing is it 
confuses people when it comes to an appendix. Before the version history? After 
the version history? Easier to take the VH out of the whole appendix question. 
There's already enough confusion around which kind of heading to use (one 
called "appendix" or just the next number in the sequence..?).

Approvals. I like to embed the approvals (usually emails in my own experience) 
for the current version only. The older versions of the doc will contain the 
older approvals. I also try to encourage people to create a separate folder 
wherever the main document lives, just to contain instances of the approvals. 
That way we can survive audits, and arguments about who may or may not have 
done what.

Version history details. A bugbear of mine (or is that a bee in my bonnet?) - 
meaningful comments. Things like "changes resulting from review comments" are 
pointless. So is "changes from workshop" - I want to know which sections have 
been changed, and if it's as a result of the workshop I want the name and date 
of it so I can look up the minutes if I have to. Assuming minutes were taken 
and stored appropriately... I don't mean every detail of every change, I mean 
something like "modified section 5 [or the name of the section] to incorporate 
details about the new infrastructure".


I have a few other preferred subjects of rant, if you care to ask...



Regards

Elizabeth Fullerton, CBAP
Business Solutions Architect
Infosys Australia
Ph: +61 3 9680 2000
Fax: +61 3 9860 2999
www.infosys.com<http://www.infosys.com>
Powered by intellect
        Driven by values

________________________________
From: austechwriter-bounce@xxxxxxxxxxxxx [austechwriter-bounce@xxxxxxxxxxxxx] 
On Behalf Of Bob Trussler [bob.trussler@xxxxxxxxx]
Sent: Tuesday, 30 June 2009 12:02 PM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Version management details in a document

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.

  23Jun09  Bob T  Added link to new server 03

There is a debate starting about the correct, or the best, or the usual, or 
I'm-used-to-this-format place to put that page with the version management and 
approval details in a document.
The page that has both
   V1.3  23Jun09  Bob T  Added new server details
and
   Approved for publication by BBBBB on 24Jun09.

There are two aspects being discussed.

ONE
Where do we put the page with the version history?
1  the full history on the front page
2  current version details only on the front page
3  following the title page
4  following the table contents
5  on the last page of the document.

During the course of a project, or during the life of the subject matter, the 
history of who did what when can get quite long and spread over several pages.
I suggested a combination of 2 and 5.

TWO
Approval or sign off notes.  These can be in two formats here.
1  one approval note for the current version.  This by implication covers all 
previous versions.
2  an approval note for each and every version, change, or update.  This note 
to be added as the last column on the version details table.

Does anyone have any idea what the current, trendy, latest way to do this and 
preferably WITH SUPPORTING ARGUMENTS.
I have looked around and found every possible variation.

Feel free to contact me off-line with examples at 
bob-trussler@xxxxxxxxxxx<mailto:bob-trussler@xxxxxxxxxxx>

Bob Trussler


**************** CAUTION - Disclaimer *****************
This e-mail contains PRIVILEGED AND CONFIDENTIAL INFORMATION intended solely 
for the use of the addressee(s). If you are not the intended recipient, please 
notify the sender by e-mail and delete the original message. Further, you are 
not 
to copy, disclose, or distribute this e-mail or its contents to any other 
person and 
any such actions are unlawful. This e-mail may contain viruses. Infosys has 
taken 
every reasonable precaution to minimize this risk, but is not liable for any 
damage 
you may sustain as a result of any virus in this e-mail. You should carry out 
your 
own virus checks before opening the e-mail or attachment. Infosys reserves the 
right to monitor and review the content of all messages sent to or from this 
e-mail 
address. Messages sent to or from this e-mail address may be stored on the 
Infosys e-mail system.
***INFOSYS******** End of Disclaimer ********INFOSYS***
**************************************************
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: