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 [EMAIL PROTECTED]
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
