Re: [comments] SPARQL Protocol against QA SpecGL ICS

Hi Kendall,

Le 05-10-17 à 16:44, Kendall Clark a écrit :
> On Tue, Oct 11, 2005 at 06:17:44PM -0400, Karl Dubost wrote:
>> I haven't been through the list of Good Practices, because the
>> document is quite bad on a QA side. You failed 5 Requirements of QA
>> Spec GL.
>
> I hope this doesn't come across badly, but it would be a good thing if
> editors of W3C specs could be made aware of this QA Spec GL thingie  
> *before*
> someone comes along and plonks them for not satisfying it!

Oh I hear you, Kendall, more than you think. We spent the last 4  
years creating the document, promoting it AND encouraging that chairs  
and staff contacts inside WGs promote it. I thought it was common  
practice now and my bad, it seems not. It means I will have to  
dedicate more of my time to this *if* we authorize me (in terms of  
resources to do so).

It's also why I'm trying to review *all* Last Call documents produced  
at W3C, I should add first WDs too. But you can imagine the time it  
takes.

So yes I deeply agree with you. It's why I was surprised by the  
document as it is and my rough comments at the start.

>> [Requirement 01: Include a conformance clause.][22]
>>     NO and no reference to a document which would contain such a
>> section.
>
> As Dan said, there is conformance content, but it's not explicitly  
> marked as
> such. I will consider remedying this, though I consider it editorial.

Yes please do. :)

>> [Requirement 02: Define the scope.][29]
>>     YES. but very little one. The scope section could be a little
>> more detailed. Look at the techniques.
>
> Can you suggest what more detail it should have? I don't know what  
> "Look at
> the techniques" means, FWIW.

QA Spec GL has been conceived to be really straightforward, you might  
consider it as a tool more than a specification itself.

Requirement 2
     Define the scope
  * What does it mean?
  * Why care?
  * Techniques
  * Examples

Requirement 02 Techniques.
[[[
     *  Make the scope easy to find.
          1. Include the scope section in the beginning of the document.
          2. Make “Scope” an item in the table of contents.
     * Write simple, direct statements of fact. Do not include any  
requirements in the scope section. Use statements such as “This  
document”:
           o — specifies a method of….
           o — specifies the characteristics of….
           o — defines….
           o — establishes a system for….
           o — establishes general principles for….
           o — is a guide for….
     * In addition to describing the subject of the specification,  
address the following to achieve a more complete scope:
           o Applicability of the specification
           o Purpose, objectives, and goals
           o Types of products or services (i.e., classes of  
products) to which the specification applies
           o Relationship to other specifications or technologies
           o What is not in scope, i.e., what the specification is  
not about
           o Limitations on the application of the specification.
       Note that it is not necessary to write a separate statement  
for each of these items; rather, they can be combined.
]]] - http://www.w3.org/TR/qaframe-spec/#define-scope-tech

>> [Requirement 03: Identify who and/or what will implement the
>> specification.][32]
>>     NO. The "classes of products" are not identified, which will
>> make it difficult to create a conformance clause.
>
> I could add a sentence or two about who might implement this spec  
> in the
> scope section. Would that suffice?

Yes definitely. Again the techniques are exactly saying what you said.

Requirement 3: Identify who and/or what will implement the  
specification.
[[[
Techniques

     * Give the classes of products in the specification:
          1. Think about all the types of products or services that  
will implement this technology, group those that are similar or  
achieve the same purpose, and determine the generic name for the  
group.  These groups are the classes of products.
          2. List these classes of products in the specification.
          3. Describe them as part of the scope.
]]] - http://www.w3.org/TR/qaframe-spec/#implement-tech

>> [Requirement 05: Define the terms used in the normative parts of the
>> specification.][36]
>>     YES. The terms seem to be defined along the text but it's not
>> obvious when it's a definition or when it's a simple explanation. A
>> consolidated glossary would help.
>
> Hmm, I don't agree with that, that it's not obvious. It's not  
> explicitly
> marked as such, but that's not the same thing.
>
> I will, however, work on a consolidated glossary. That's a reasonable
> request and earlier versions of this doc had a glossary.

Thanks. And it helps to define the general W3C glossary.
     http://www.w3.org/2003/glossary/

and not to redefine too much terms which have been already defined.


>> [Requirement 07: Use a consistent style for conformance requirements
>> and explain how to distinguish them.][40]
>>     YES. you are using the RFC2119 keywords in the document to
>> define your requirements. Though be careful sometimes, you are using
>> a double requirement in the same sentence which might lead to
>> misunderstanding. For example, in 2.1.4 "Any message after the first
>> in the pattern may be replaced with a fault message, which must have
>> identical direction."
>>
>
> Huh? That seems perfectly straightforward to parse. This is purely  
> editorial
> IMO. I'm not convinced it's a problem.

     I'm not convinced too. I was wondering if it would be a problem  
for writing a test assertion without ambiguity. If you are convinced  
fine by me.

> One thing that might be said about W3C specs is that they are very  
> ugly to
> read, at times, which just might have an impact on comprehension.  
> As someone
> who commented on W3C specs for many years, profesionally, I've  
> certainly had
> that experience many times.

Yes agreed. :) And it's why I'm so pushy (too much ;) ) about the  
clarity of a specification and to be as much explicit as possible.


>>     Sometimes you are using may and it's not sure in which context.
>
> I can't parse this sentence.

Sometimes you are using the word "may" but apparently not in the case  
of a RFC 2119 as in plain english, which has driven me to the  
following comment:

>> For example "The QueryRequestRefused  fault message does not indicate
>> whether the server may or may not process a subsequent, identical
>> request or requests." is not in bold.
>
> Yes, because it's not the requirement signalling "may", it's the  
> ordinary
> English word "may".

Yes, I understood that, but I have seen many people being not able to  
understand that, specifically people who are not native English  
speakers. Something which helps often is to have a list of the  
testable assertions and/or a test suite for all requirements. :)  
which I believe will come soon.

>> To avoid this kind of
>> situation, we recommend in QA guidelines to avoid the use of
>> normative prose when it's not intented to be.
>
> Uh, "normative prose" meaning the English modal verb "may"? With  
> all due
> respect to the "we" who recommends, that's enormously STUPID. IMO. :>

:) Don't forget that yes people who are implementing specs will  
misunderstand. Unfortunately, it's something which is happening all  
the time.

>> [Requirement 08: Indicate which conformance requirements are
>> mandatory, which are recommended, and which are optional.][41]
>>     NO.  if we consider the fact you are using RFC 2119, we could
>> say yes, but there's also the fact that you do not define which
>> sections in your document is normative or not normative.
>
> So that's a YES, then, right? Why would you *not* consider the fact  
> that
> we're using RFC 2119 terms to indicate conformance requirements?  
> That's like
> saying that if you don't consider the fact that the document is  
> written in
> English, then it could be written in German. Gah!

2.2.1 HTTP Examples
http://www.w3.org/TR/2005/WD-rdf-sparql-protocol-20050914/#query- 
bindings-http-examples

     Is it a normative section?

3. Policy considerations
http://www.w3.org/TR/2005/WD-rdf-sparql-protocol-20050914/#policy

     Is it a normative section?

>> [Requirement 11: Address Extensibility.][52]
>>     NO. This has not been addressed at all. Create a section on
>> extensibility and explain the extensibility, requirements or your
>> language. If it's not extensible, say it. (As a side comment,
>> extensibility as it is defined in QA, not TAG ;)  to avoid
>> misunderstanding)
>
> Stealing or adapting WSDL 2.0's extensibility language seems a  
> reasonable
> thing to do.

See the other mails about it :)

http://lists.w3.org/Archives/Public/public-rdf-dawg-comments/2005Oct/ 
0043
http://lists.w3.org/Archives/Public/public-rdf-dawg-comments/2005Oct/ 
0042

Thanks again.

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***

Received on Tuesday, 18 October 2005 19:01:13 UTC