Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: forrest-dev@xml.apache.org
Message-ID: <3DD2A0D9.8060801@apache.org>
Date: Wed, 13 Nov 2002 13:58:33 -0500
From: "Andrew C. Oliver" <acoliver@apache.org>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.2b) Gecko/20021016
MIME-Version: 1.0
To: forrest-dev@xml.apache.org
Subject: Re: Forrest is overdocumented
References: <04A68DAE-F71D-11D6-9EF5-0030653FE818@apache.org>
In-Reply-To: <04A68DAE-F71D-11D6-9EF5-0030653FE818@apache.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

>
>
>>
>>
>> You're wrong.
>
>
> Please, let's not polarize what might be a very interesting thread.


My sincere appologies, I'm conducting an experiment in sleep deprevation 
and high levels of stress and what effect they have on my already 
tactless personality with deficient  e-mail tact skills.  what I meant 
to say "I disagree with that viewpoint...have you considered..."

>
>> This is like saying "import statements" should just be guessed at 
>> because worrying about what dependencies the code has will overwhelm 
>> the developers/users...
>
>
> I don't think that's a fair analogy. Your example referred to methods, 
> not classes... And by overwhelming, I'm not talking about "worrying" 
> users or committers, but about how such potentially voluminous 
> feedback (during a build) will be processed (e.g. not ignored).

No...thats still fair.  The compiler does this for code..  So I'm just 
saying...Extend it...Do it for docs.  We're kinda sorta seeing the 
opposite effect...extending the documentation to control the code 
(xdoclet)....flip it over.  If the documentation depends on the 
code..check for it.  If you're getting volumnous feedback, you have 
volumes of doc work to do.

>
>>  (I'm not sure what hte user has to do with the doc part either...the 
>> tool is supposed to resolve it)
>
>
> By user I meant users who contribute/patch docs. There is a growing 
> number of these kind of users, at least on Cocoon.

And presumably they learned this information from somewhere right?  Was 
it a config file?  Well presumably a developer write some documentation 
in the config file...  If he documents that documentation's dependency, 
the documentation developer whom is also a user can site that 
documetnation and the dependency tree is maintained.  

>>
>> Well presumably your documenting lower level concepts at a higher 
>> level. Presumably the higher level documentation should DEPEND upon 
>> the lower level docuemntation, include portions where possible, and 
>> specify dependencies upon it.
>> <doc-depend class="org.apache.bla" method="doda(int)"/> in the low 
>> level docs...
>
>
> Problem is, there's isn't always a clean 1-to-1 mapping, especially 
> when dealing with layers of the architectural and user models. Can you 
> think of a way we could deal with a subset of code/components when 
> documenting such dependencies? Think about a document about the 
> sitemap for Cocoon. Imagine how many dependencies it would have if you 
> included all associated methods.

So you're saying this won't work ALL of the time.  Agreed.  My response 
(and I mean this in the most tactful way) is "so what?"   What 
percentage improvement makes this worthwhile?  

>
> Yes, but having it similar to javadocs sounds redundant.

Okay....so maybe its not a good idea...  I dunno.  I don't presently 
have time to POC it out so I just thought I'd throw it out there.  Maybe 
I'm wrong...that happens.

What I am positive I'm right on is the title of this thread.  That is 
complete (and excuse how harsh this is) bunk.  You cannot overdocument. 
 But you say you can have reams and reams of documentation that is 
useless and (not to say we do just for the purpose of demonstrating this 
point) not up to day.  That is UNDER documentation.  You've put 
insufficient effort into organizing it, editing it and updating it.  So 
its still UNDER-documetnation.  you can NEVER over document until your 
user has a complete intuitive understanding and you're telling him how 
to brush his teeth before he uses the software...  (silly, but I mean it)...

So effort needs to be put into EFFECTIVELY documenting it, not volume. 
 For isntance, I send about 200x as many emails as Stefano.  But it 
takes me that many to get my point accross because I'm not that good at 
email communication (sucks to be me).  I also don't often put enough 
time and consideration into the effort, where stefano does.  This isn't 
to say I'm over-emailing, I'm still under emailing.  One Stefano email 
gets the point accross much better because he puts way more thought and 
effort into it.  Same thing with doco...  (Only thats one thing I'm 
better at then most... ;-) )...

-Andy

>
> Diana
>
>