forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: Forrest is overdocumented
Date Tue, 12 Nov 2002 15:45:54 GMT
> 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 ;-)
>

But please read again DO NOT ELIMNATE CONCEPTUAL DOCUMENTATION!  Just 
enhance "compile-time-checking" ;-)


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



Mime
View raw message