Re: Issue 29rec is closed [Re: Suggested Minor Errata for "Resource Representation SOAP Header Block" http://www.w3.org/TR/2004/PR-soap12-rep-20041116/ ]

Hi Yves,

Why not, if only to reinforce the point, just add "(Non-normative)" to
the heading of section 4.3.3. Yes, reading section 1.1, examples are
explicitly non-normative. But, a casual reader may miss that (I did).
Repeating the point, by adding "(non-normative)" to the heading of
section 4.3.3, does no harm, and avoids any possibility of confusion.

In particular, when I read it at first, I did not understand precisely
what in 4.3.3 was an example - I thought it was an example of the HTTP
Resolver functionality in the specification, when the correct
interpretation is that the HTTP Resolver is not functionality of the
specification, but just an example of possible functionality that
could be built on the foundation of the specification. So,
furthermore, why not add a note to say "The HTTP resolver extension
described in this section is not part of this specification, but
rather an example of the power of the extensibility of this
specification".

Another point is the sections use of MAY. Certaintly, a conforming
implementation MAY implement any extensions to a standard which are
compatible with the standard that it wishes. But "MAY" makes it sound
like it is describing an optional feature, as opposed to a   specific
application of the general principle that conforming implementations
MAY incorporate whatever optional extensions they wish (provided they
follow the rules governing how to properly declare and use
extensions.). I would suggest not using RFC 2119 in this section, and
removing the capitalisation of MAY, or rewording the sentence to avoid
the word "may" altogether.

A further point is that this example makes use of a www.w3.org
namespace, which gives the impression that it is some form of standard
or work-in-progress. Using a  www.example.{com,net.org} makes it
clearer that it is just an example. I would argue it would be better
to only www.w3.org namespaces for functionality adopted by or under
consideration by the W3C, and not for mere examples. If someone was to
propose this functionality for consideration (e.g. make a proposal for
it in a working group or as a member submission), then using a
www.w3.org namespace in *that document* would be appropriate, because
then it would no longer be an example.

So, my proposed solution:

1. Either add "non-normative" to section 4.3.3, or renumber 4.3.3 as Appendix C.
2. Add a note to the beginning of 4.3.3, or reword its introduction,
to make clear that the purpose of this section is to demonstrate the
power of the extensibility mechanism, and not  define an extension.
3. Remove the capitalisation of MAY in section 4.3.3, or even better
reword it to use a different word altogether.
4. Change the namespace URI of the example to use
www.example.{com,net,org}, instead of www.w3.org.

None of these changes are essential, but I feel that some or all of
them would improve the clarity of the document, with very minimal if
any costs involved. (Clarity is more than just technical correctness
-- it is also trying to avoid where possible misleading the lazy
readers like me who will misinterpret things if the specification
authors give them the chance.)

Cheers
Simon

On 5/9/05, Yves Lafon <ylafon@w3.org> wrote:
> On Thu, 27 Jan 2005, Simon Kissane wrote:
> 
> Simon,
> In section 1.1, you may find:
> 
> <<
> All parts of this specification are normative, with the exception of
> examples and sections explicitly marked as "Non-Normative".
> >>
> 
> So, examples are explicitely non-normative. As 4.3.3 is clearly labelled
> as being an example, it is by definition non-normative.
> So the Working Group decided to close this issue with no actions taken, as
> the specification is clear enough on the status of section 4.3.3.
> 
> Please let the Working Group know if that resolution to the issue 29rec
> [1] is acceptable or not as soon as possible.
> Regards,
> 
> [1] http://www.w3.org/2000/xp/Group/xmlp-rec-issues.html#x29
> 
> > ---------- Forwarded message ----------
> > From: Simon Kissane <skissane@gmail.com>
> > Date: Sun, 23 Jan 2005 21:10:25 +1100
> > Subject: Suggested Minor Errata for "Resource Representation SOAP
> > Header Block" http://www.w3.org/TR/2004/PR-soap12-rep-20041116/
> > To: xml-dist-app@w3.org
> >
> >
> > Hi,
> >
> > My interpretation of the "Resource Representation SOAP Header Block"
> > is that section 4.3.3 is non-normative, which I believe is the
> > interpretation everyone would agree with. However, the first time I
> > read it, I formed the impression that the "HTTP resolver"
> > functionality in it was some form of optional part of the
> > specification. I might suggest, that to avoid any such impression
> > being formed in the minds of a less than careful reader, that the
> > section be moved to an appendix and clearly marked as "NON-NORMATIVE".
> > (At first, I read the wording "Extension example:"  to mean, not that
> > this section is non-normative, but that this part of the specification
> > is an example of the power of the extensibility mechanisms in the
> > specification.)
> >
> > Also, I could not find a public comment email address, or editors
> > email addresses, for this specification, so I am reporting it here. Is
> > this the right place? I would suggest that every recommendation should
> > clearly identify in its introduction how errata or other such issues
> > are to be raised.
> >
> > Cheers
> > Simon Kissane
> >
> 
> --
> Yves Lafon - W3C
> "Baroula que barouleras, au tiéu toujou t'entourneras."
> 


-- 
Simon Kissane
http://simonkissane.blogspot.com/

Received on Tuesday, 24 May 2005 09:41:40 UTC