atw: Re: Version management details in a document
- From: Elizabeth Fullerton <Elizabeth_Fullerton@xxxxxxxxxxx>
- To: "austechwriter@xxxxxxxxxxxxx" <austechwriter@xxxxxxxxxxxxx>
- Date: Tue, 30 Jun 2009 13:39:44 +1000
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:
