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 15:30:54 GMT

Andrew C. Oliver wrote:
> I'm verklempt.... I need a moment....talk amongst yourselves....here 
> 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 
> classname="org.apache.poi.hssf.usermodel.HSSFCell" 
> 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.

Nice.

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

User request number 1.
Keep tracking guys ;-)

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