Subject:
Re: is revhistory _that_ needed?
From:
David Lawyer ####@####.####
Date:
27 Nov 2003 00:03:39 -0000
Message-Id: <20031127000204.GA340@lafn.org>
On Tue, Nov 25, 2003 at 11:18:45PM -0800, Tabatha Marshall wrote:
> 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.
For most people, if a HOWTO doesn't cover what they need to know, they
find the info elsewhere and don't go back looking in the HOWTO to see if
it's been included. Or if they do look at it again, they are likely
trying to solve a different problem since they found out the info about
their original problem elsewhere. They aren't really too concerned if
it's been included. But some people would like to know about recent
changes, including those who may have made comments and wonder if the
comment was ever acted upon. Even in this case, one may search the text
of the doc to see if it was included.
Another point is that a revision history may not tell one if something
has been included. For example, in the history it may say: revised
section on ... " and it may not give you the details of what's changed
in the revision that wasn't formerly covered. Sometimes, I wonder if
it's really important to say that some typos were fixed or that a broken
url was fixed.
Thus, I think it's usually a good idea to have a revision history but
not always required. I think for a minor revision of fixing some typos
or broken urls, then that revision history isn't very important. But for
a major change, it is important to document it.
> 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)
>
>
> ______________________ http://lists.tldp.org/
>
>
David Lawyer
