cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylv...@apache.org>
Subject Re: [docs] old docs import done
Date Fri, 17 Jun 2005 17:03:39 GMT
Bruno Dumon wrote:

>On Fri, 2005-06-17 at 17:15 +0200, Bertrand Delacretaz wrote:
>  
>
>>Le 17 juin 05, à 17:08, Upayavira a écrit :
>>    
>>
>>>...a document detailing how the HTMLGenerator works, with all of its 
>>>options, wouldn't be that useful in other parts of the documentation 
>>>(other than as a link), IMO.
>>>      
>>>

Agree. The reference section should be distinct from the tutorial 
section ("section" meaning here either site of navigation subtree), 
furthermore considering that a single component can be referenced from 
several places in different tutorials.

>>IMHO such reference documents should have permanent and predictable 
>>short URLs, say "reference/components/HTMLGenerator" in this case. 
>>That's hoping these will be generated automatically of course, at some 
>>point.
>>    
>>
>
>Depends a bit on what is part of the automatically-generated docs. IMHO
>documentation that provides usage notes on components (thus, which is
>not really javadoc) should better not be maintained as javadoc. For
>example, take the I18nTransformer. There's a very very long javadoc
>there which is essentially user documentation and is very hard to
>read/maintain in the form of javadoc.
>  
>

+1. A lot of components have their user docs in the javadoc as it wasn't 
much harder to write it there rather than in xdocs. Things are different 
now :-)

>I am +1 though on merging technical information on the component (such a
>it is cacheable, is it poolable, ...) automatically from the sources.
>  
>

Yup.


Sylvain

-- 
Sylvain Wallez                        Anyware Technologies
http://apache.org/~sylvain            http://anyware-tech.com
Apache Software Foundation Member     Research & Technology Director


Mime
View raw message