discuss: Revision history at end of document
Subject:
Re: Revision history at end of document
From:
Tabatha Marshall ####@####.####
Date:
14 Jan 2004 22:20:04 -0000
Message-Id: <1074118776.4941.43.camel@mysticchild>
On Tue, 2004-01-13 at 13:29, Ruth A. Kramer wrote:
> Must be my day to delurk. ;-)
Glad to see ya!
> As a reader, here's how I think I'd like to use the revision history.
>
> Let's say I've read (or skimmed) the Made Up HOWTO, version 1.1 at some
> point in time. Now I'm using Made Up and have a question that I don't
> recall being covered in the HOWTO. Althought I 'd probably search
> Google first, eventually I might try to retrieve
> the latest version of the Made Up HOWTO (maybe 2.3??) and check the
> revision history to see if the topic I'm looking for has been addressed
> in one of the revisions since I last read / skimmed the document.
And here is the nature of our problem: how are we to know what previous
version someone might have read, and thus, what revisions they might be
looking for when they come to TLDP?
> If the total revision history was buried in CVS or not easily
> accessible, I might experience some frustration. (On the other hand,
> assuming the latest revision is on line and indexed in Google, I
> probably would not need to consult the revision history.)
The revision history, being of DocBook design, is set up to display in
the bookinfo or articleinfo of a document when used properly. I'm sure
David Lawyer will agree with me when I say that I think it's the design
that's in question - whether this is the most appropriate place for such
a thing, if at all. :D
> Just to provoke discussion, what needs does the revision history serve
> for an author (and what does it take to satisfy those needs?)? If it is
> only for the author, keeping it in CVS / source is probably adequate.
My position on it has always been that it's important to see SOMETHING
in the revhistory, if the document is in DocBook. The number of
revisions is another story, which is why I support keeping the latest
revision entry at the top and keeping a history of it elsewhere, such as
in source an appendix - the only problem with an appendix is that the
tags themselves are made to be entered a certain way or they won't work,
and some people can't deal with reading source, so I'm not sure how
feasible either idea is.
Having written documents using DocBook myself, I've always left the
complete revhistory at the top, but became more discriminating as to how
often I'd update. But not everyone can be expected to do things the
same way I do, and I'm sure this method is not without its faults. :D
Discuss away!
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)
