You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by Dennis Sosnoski <dm...@sosnoski.com> on 2006/11/11 21:33:41 UTC
[Axis2] Documentation standards
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,
and substituting the '>' entity for '>'. None of these changes seem
especially useful to me. The last change, in particular ('>' 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'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.
- Dennis
--
Dennis M. Sosnoski
SOA, Web Services, and XML
Training and Consulting
http://www.sosnoski.com - http://www.sosnoski.co.nz
Seattle, WA +1-425-296-6194 - Wellington, NZ +64-4-298-6117
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org
Re: [Axis2] Documentation standards
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
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 '>' entity for '>'. None of these changes seem
> especially useful to me. The last change, in particular ('>' 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 <xxx> harder to read than <xxx>. 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
Re: [Axis2] Documentation standards
Posted by Davanum Srinivas <da...@gmail.com>.
Ron,
Where's is this problem? ('>' for '>')
thanks,
dims
On 11/11/06, Ron Wheeler <rw...@artifact-software.com> wrote:
> IMHO, just be happy that people are taking an interest in cleaning or
> doing anything with documentation.
> The lack of care and feeding of documentation is the general curse of
> open source software.
>
> I am doing battle with another package that is completely devoid of
> comments in all of the code including the samples that are supposed to
> show one how to use the package.
>
> The ('>' for '>') is a bit hard to fathom. Perhaps the author has an
> explanation.
>
> Just say thanks to anyone who takes the time to care.
>
> Ron
>
> 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, and substituting the '>' entity for '>'. None of these
> > changes seem especially useful to me. The last change, in particular
> > ('>' 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'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.
> >
> > - Dennis
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-dev-help@ws.apache.org
>
>
--
Davanum Srinivas : http://www.wso2.net (Oxygen for Web Service Developers)
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org
Re: [Axis2] Documentation standards
Posted by Ron Wheeler <rw...@artifact-software.com>.
IMHO, just be happy that people are taking an interest in cleaning or
doing anything with documentation.
The lack of care and feeding of documentation is the general curse of
open source software.
I am doing battle with another package that is completely devoid of
comments in all of the code including the samples that are supposed to
show one how to use the package.
The ('>' for '>') is a bit hard to fathom. Perhaps the author has an
explanation.
Just say thanks to anyone who takes the time to care.
Ron
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, and substituting the '>' entity for '>'. None of these
> changes seem especially useful to me. The last change, in particular
> ('>' 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'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.
>
> - Dennis
>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org