forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Forrest is overdocumented
Date Wed, 13 Nov 2002 15:31:45 GMT

On Wednesday, November 13, 2002, at 09:13  AM, Andrew C. Oliver wrote:

>> I fear this approach is a bit oversimplistic, paticularly for projects 
>> with large amounts of code. Some docs would have dependencies on 
>> *many* classes. Potential contract violations (revealed during the 
>> build process??) would overwhelm committers/users.
>
>
> You're wrong.

Please, let's not polarize what might be a very interesting thread.

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

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

>
>>
>>> Secondly.  Move the documentation as close to the code as possible 
>>> while making the conceptual documentation depend on it!
>>
>>
>> Can you elaborate?
>
> 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.

> At the high level you should be including sections of the low level 
> docs (DONT REPEAT YOURSELF) and then <doc-depend doc="blabla.xml" 
> section="bla"/> -- Then if the low level doc is broken, the high level 
> doc is marked broken as well.  Or if the low level doc deletes that 
> section...the high level doc is broken as well.  Furthermore high level 
> docs might depend upon code structures as well.  For instance, in the 
> case of ANT if I'm describing how to use the JUNIT task and I'm 
> describing the printsummary attribute, I can obviously refer to that 
> attribute in the low level implementation of the Junit taks (which I 
> think is 
> org.apache.ant.somethingsomething.tasks.JUnitTask.setPrintSummary
> (bla) ) --
> This will catch things like changes in how configuration files work, 
> directory structure, etc.  It won't catch functionality changes.  If 
> I'm describing how printsummary works and now suddenly it does 
> something different but has the same attributes/etc... This won't catch 
> that.  But thats crappy programming probably anyhow.
>
> I think this will help reduce the weight of maintaining documentation 
> on developers and its invisible to users anyhow.  Its drawback is that 
> it may not always be natural to create a heirarchial structure that 
> this seems to dictate, but I think its clean...
>
> The rest of the time the documentation should be as close to the code 
> as possible...I'm not sure how much more I can elaborate on that.... 
> Like Javadoc kinda sorta...

Yes, but having it similar to javadocs sounds redundant.

Diana


Mime
View raw message