From cocoon-dev-return-29429-apmail-xml-cocoon-dev-archive=xml.apache.org@xml.apache.org Fri Jul 12 14:10:20 2002 Return-Path: Delivered-To: apmail-xml-cocoon-dev-archive@xml.apache.org Received: (qmail 14011 invoked by uid 500); 12 Jul 2002 14:10:19 -0000 Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: cocoon-dev@xml.apache.org Delivered-To: mailing list cocoon-dev@xml.apache.org Received: (qmail 14000 invoked from network); 12 Jul 2002 14:10:19 -0000 Message-ID: <3D2EE1F2.1000905@apache.org> Date: Fri, 12 Jul 2002 10:04:34 -0400 From: "Andrew C. Oliver" User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.0.0) Gecko/20020530 X-Accept-Language: en-us, en MIME-Version: 1.0 To: cocoon-dev@xml.apache.org Subject: Documentation and abbreviations Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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