cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Piroumian Konstantin <KPiroum...@protek.com>
Subject RE: Documentation and abbreviations
Date Fri, 12 Jul 2002 14:15:01 GMT
Having a glossary of terms would be also fine.
We should think about it on Forrest. (I could provide a sample, but it's in
Russian).

Konstantin


> From: Andrew C. Oliver [mailto:acoliver@apache.org] 
> 
> 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 ;-)

-Andy



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

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


Mime
View raw message