forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
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:
> 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         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message