axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sanjiva Weerawarana <sanj...@opensource.lk>
Subject Re: [Axis2] Documentation standards
Date Mon, 13 Nov 2006 04:11:32 GMT
On Sun, 2006-11-12 at 09:33 +1300, Dennis Sosnoski wrote:
> There's been a lot of churn in the documentation lately, IMHO not all of 
> it useful. For instance, people have been going through replacing 
> abbreviations (haven't, shouldn't) with the full words (have not, should 
> not), reformatting HTML so that </p> tags are always on their own line, 

It seems to me s/haven't/have not/g etc. is a good thing in a proper
written document! I don't care about </p> on its own line however.

> and substituting the '&gt;' entity for '>'. None of these changes seem 
> especially useful to me. The last change, in particular ('&gt;' for '>') 
> is unnecessary and makes embedded XML more difficult to read when you're 
> looking at the "raw" document text (i.e., in a text editor rather than a 
> browser).

I personally find the &lt;xxx> harder to read than &lt;xxx&gt;. Clearly
YMMV. Whatever it is we need to be consistent, at least within each
document. 

> I'd like to propose that people do not make arbitrary formatting changes 
> in the documentation updates. If they're using a tool that forces such 
> changes they should find a new tool, just as is the case with changes to 
> the actual code.

Let's agree on the doc standards and put them up somewhere, maybe next
to the code standards. 

Sanjiva.



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org


Mime
View raw message