discuss: is revhistory _that_ needed?
Subject:
Re: is revhistory _that_ needed?
From:
Tabatha Marshall ####@####.####
Date:
25 Nov 2003 22:44:15 -0000
Message-Id: <1069800227.21421.62.camel@mysticchild>
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'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.
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)
