forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <>
Subject Re: Forrest is overdocumented
Date Tue, 12 Nov 2002 15:25:12 GMT
I'm verklempt.... I need a amongst 
I'll give you a topic
Compilable dependency resolution.  I'll leave the XML->XML version of 
this to the geniuses but for the java version any contract mentioned in 
the documentation should have an <element-dependancy 
method="getFormat(int)"/> and if ever the getFormat(int) method goes 
away or something the compilation of the XML will fail and I'll be 
forced to update it.

Secondly.  Move the documentation as close to the code as possible while 
making the conceptual documentation depend on it!

Nicola Ken Barozzi wrote:

> 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 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

View raw message