forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: Forrest is overdocumented
Date Tue, 12 Nov 2002 14:59:24 GMT

Jeff Turner wrote:
> I never thought I'd say it of an Apache project, but there you go.. :)

Keep this mail as a reference for future discussions on the "Avalon 
Documentation Team" ;-)

> Users are practically swimming in documentation, unfortunately mostly
> slightly out of date.  I foolishly tried to update the Forrest Primer,
> and found that outdated xml.apache.org-centricity is absolutely
> everywhere.  Rewriting an existing doc is actually more effort than
> writing one from scratch, because added content has to 'fit', not
> duplicating anything.  The change 'infects' the doc around it, requiring
> a cascade of updates.  primer.xml is a nightmare because it touches
> everything.

Since I seem to be the "let's make a tool to solve the problem"-man, 
here goes the tool ;-P

I had presented this before, and now is the case it could have helped 
(maybe?).
That is keep in the document the "expiry date" of the document itself, 
and eventually its binding with other document update dates.

For example, we could say that if build.xml has changes for a week, the 
primer document may be stale...

Just a RT in the midst of Jeff's rantings...

> IMO the site needs a ground-up rewrite, containing the absolute minimum
> of content.  We could have a separate tab, 'legacy', containing the
> current site.
> 
> </rant>
> 
> :)
> 
> Though I must say, the quality of Forrest's docs (before the code changed
> under it) says a lot about the dedication of Forrest's committers.  The
> site authors all deserve some serious toothbrush awards.

+1

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message