cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: Documentation and abbreviations
Date Fri, 12 Jul 2002 14:19:58 GMT
Andrew C. Oliver wrote:
> Hi All,
> 
> this is mostly a pedantic issue.  But one thing that bugs me about much 
> of the existing cocoon documentation is the style in which
> Cocoon-specific abbreviations are used.  A good example:
> 
> http://xml.apache.org/cocoon/userdocs/xsp/index.html
> 
> The most basic question is "What does XSP stand for?"  From there, one 
> could almost guess what it is essentially.  My suggestion to
> documentation writers is that when using an abbreviation think "Is the 
> standard Java developer using Cocoon for the first time going to know 
> what this means".
> 
> My suggestion in the case they won't, use an abbreviation introduction 
> for the first use in the document as follows:
> 
> ---
> 
> Here will soon appear an overview of the user perspective of eXtensible 
> Server Pages (XSP).
> 
> ---
> 
> from then on its safe to use the abbreviation and the reader will know 
> what you mean. 
> I believe that doing this will prevent Cocoon documentation from reading 
> like an eyechart ;-)

Even better, we make a link creating Transformer that transforms all 
instances of " xsp " to a link that links to a cocoon terms dictionary.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message