Re: [comments] SPARQL Protocol against QA SpecGL ICS

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!

> [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.

> [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.

> [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?

> [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.

> [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.

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.

>     Sometimes you are using may and it's not sure in which context.  

I can't parse this sentence.

> 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".

> 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. :>

> [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!

> [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.

Cheers, 
Kendall
--
Sad songs and waltzes aren't selling this year... --Cake

Received on Monday, 17 October 2005 20:46:14 UTC