cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Documentation and abbreviations
Date Fri, 12 Jul 2002 14:04:34 GMT
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


Mime
View raw message