discuss: is revhistory _that_ needed?
Subject:
Re: is revhistory _that_ needed?
From:
David Lawyer ####@####.####
Date:
26 Nov 2003 05:50:16 -0000
Message-Id: <20031126051332.GB475@lafn.org>
On Tue, Nov 25, 2003 at 02:43:47PM -0800, Tabatha Marshall wrote:
> On Tue, 2003-11-25 at 10:02, David Lawyer wrote:
> > On Tue, Nov 25, 2003 at 09:34:08AM +0200, Artemio wrote:
> > > Hello!
> > >
> > > I just thought I should take the revision history away from my
> > > SquashFS HOWTO - just because it seems unneeded, as for me.
> > >
> > > Is it a requirement for all HOWTOs or it's okay to omit it?
> >
> > I think that it's best to just have the whole revision history in
> > the source only (as a comment). Except that for the recent
> > revisions (within the past several months), I think they should also
> > be in the document. I don't think it's required to have a revision
> > history.
>
> One technique some authors have used, which I find very agreeable to
> the aesthetics of the doc, is to put the latest one or two revision
> entries at the top and record the remainder of them in a separate
> section.
I like just having the date and version number at the top. Then, one
starting to read the doc doesn't need to see any revision history at
all. Then in the introductory section, I list only recent revisions
that someone reading the doc might want to either look at (or skip
over). Hiding the complete revision history in the source lets anyone
who's really interested find it, since the source is on LDP's site. It
saves on bandwidth by making the doc a little shorter and it's no
trouble to do since its right in the source inside comment tags (Docbook
should provide a hidden-revision-history tag for this purpose :-).
But source is not as easy to find at the LDP site as it should be. How
does the reader know if it's DocBook or LinuxDoc if they look for it in
CVS? The place to look is in the docbook file, not in CVS, but do
people browsing the site know this?
> I've done this often in the case of new docs, where the author has
> tracked revisions prior to the 1.0 release, showing only 1.0 in the
> revhistory and putting the remainder into a historical section (at the
> preference of the author wanting to keep such a history).
>
> It's not a good idea to have too many entries, since they clutter up
> everything above the document's abstract, and can make the TOC show
> too far down the page. Consolidation or another section or even
> hiding it in the markup are all good ideas if the revhistory gets too
> convoluted. But in my opinion, at least the latest revision should
> show, for readers who want to know how up to date the work is.
>
David Lawyer
