discuss: is revhistory _that_ needed?
Subject:
Re: is revhistory _that_ needed?
From:
Tabatha Marshall ####@####.####
Date:
26 Nov 2003 07:19:13 -0000
Message-Id: <1069831124.21903.149.camel@mysticchild>
On Tue, 2003-11-25 at 22:19, Artemio wrote:
> you wrote:
> > But in my opinion, at least the latest revision should show, for readers
> > who want to know how up to date the work is.
> But why do I need it to show up as revision history, if I have the publishing
> date and version specified?
Think of it this way. I went and read your HOWTO when you first had it
published at LDP. There was something missing, or a scenario that
wasn't covered, for example. Six months later I head back to the LDP
and stumble on your document. I wonder if you ever did anything about
that. I look at the front page, so I don't have to sift through the
document source or the actual contents. Just the very first screen.
And LO! There it is! A revision entry, telling me that you've made
some changes, and you've now included a section with the stuff I
wanted! YAY! I'm reading this HOWTO, now that I know. Thank goodness
I didn't have to go through all kinds of stuff to figure out what you
changed! Thank you, Author, for not making me look through CVS, since
I'm terrible with CVS, and thank you for not burying a description of
your changes in an obscure place in your HOWTO, so I could figure if I
wanted to bother looking at it again!
> Can I just keep the current version and pubdate and comment the revhistory for
> just my own memo?
I've heard complaints about lengthy rev histories, but other than that,
this is the first time I've heard issues over including it. From what I
can see, it's been done this way for a long time, and the DocBook markup
tags are designed with that in mind. Could it go into its own section?
Sure - a revhistory can be within an appendix. But it was not designed
to be nested in regular sections, and is most often used at the
beginning of the document.
If you want to confirm that, just look at the DocBook Definitive Guide's
example of an article: http://www.docbook.org/tdg/en/html/article.html.
In other words, the tags were designed to be at the front or in an
appendix, maybe for historical value.
I always check a rev history when I want to read/use a HOWTO. I like
knowing if a document's been revised, particularly if I used it and had
problems. In corp-speak, this type of offering is called "Value-Added
Service" and makes for good customers.
I would prefer it if you included a rev history, but I alone don't speak
for LDP. If everyone disagrees with my logic and wants to do it
differently, I'll be glad to hear your reasons against it. But the only
reason against it so far is because we already have a pubdate. That's
great, but it doesn't tell you what happened lately, does it?
Tab
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
