Re: Editorial thoughts on qaframe-spec

At 06:51 PM 10/14/02 +0200, Dominique Hazaël-Massieux wrote:
>[sent to the WG list because this is mostly editorial stuff, but please
>send any technical reply in CC to www-qa]

I'll split my reply.  About your GL 3,4,7 thoughts, I'll send a second message.


>http://www.w3.org/QA/WG/2002/09/qaframe-spec-inprogress.html
>
>I hope you all had a safe trip back; I really enjoyed last week meeting
>and think it was really productive.

Yes, we covered a lot.  I have the feeling that we have a direction now 
that will converge successfully (tho' lots of work and some tough problems 
still remain).


>I've started working on the new version of qaframe-spec, and have a few
>thoughts to share.
>
>First thing I'm trying to do is to harmonize and formalize our
>checkpoints,

I'm thinking that I should make these changes simultaneously with OpsGL/ET, 
for the 1-nov publication.  What do you think?

>which consists in:
>- producing test assertions for each CP with a capitalized RFC2119
>keyword; most of the time, I try to use MUST and reserve SHOULD for
>assertions we're not sure how broad their usage is. I've not used MAY so
>far and don't think we should
>- using consistent verbs between CP (define, provide, describe,
>identify, indicate), removing non testable adverbs and phrases (clearly,
>make it clear, ...)
>- distinguishing examples and rationales, so that it's easier later to
>see what's normative and what's informative only
>
>[the draft I'm working on is available at
>http://www.w3.org/QA/WG/2002/09/qaframe-spec-inprogress.html ; its
>default stylesheet shows everything that has been inserted and deleted,
>there is an alternate stylesheet available for a lighter reading]

It is good to look at the styled draft (but not with old NN!), especially 
to see what is being deleted.

Question.  Does most of the deleted stuff -- or at least lots of it -- get 
migrated to Spec Extech?


>I have not worked at all on the introductory section, since I think
>Lofton plans to do it. I'll try to propose a plan for this section ASAP.

Okay.  My initial idea was mostly to cut, simplify, tighten, and 
condense.  Especially the first 2 sections ("1.0" and 1.1) are too long, 
too detailed, and redundant.  A couple of preliminary thoughts for 
editorial re-org of Chapter 1:

0.) Rewrite first two sections ("1.0", and 1.1 Motivation) and cut a lot.

1.) Combine the "Major themes" and "Variability, complexity, and roadmap of 
guidelines" sections into a single, simpler roadmap section.

2.) In the new roadmap, eliminate the "major themes" distinction.

3.) Replace it, plus the distinctions in the first two paragraphs of the 
"Variability..." section, with a simpler organization:
-- the guidelines divide naturally into two classes...

-- GL 2-9 are the DoV guidelines, which address ways in which the defined 
technology features and conformance policies may lead to conformance 
variability amongst implementations;

-- the rest (1, 10-15) concern features of the specifications (documents) 
per-se.

Now this simple binary classification ignores a problem that Dominique 
alludes to next.  As I view it, especially in GL2-9 there is confusion 
between the specified technologies on the one hand, and the specifications 
(actual documents) that define the technologies and their conformance 
rules, on the other hand.  Specifically, the divisions of technology which 
are in effect, and/or variability of conformance, may not align neatly with 
packaging and possible partitioning of the specification(s).

More about that later, on the IG list (is that the right place for it?).

But for now ... any thoughts on preliminary sketch of changes to Chapter 1?

(Btw, my thought was to make a draft sometime this week, and submit it for 
QAWG review/comment.  But I'll hold off, if you think I'm way off the mark 
with above ideas.)

-Lofton.

(P.S. More on Dom's following substantive issue in a near-future message...)


>As now I have to work on the DOV GL (currently GL 3,4 and 7), I have
>thought of a new way to understanding these GL and would like to get
>feedback on this, especially from Lynne and Lofton. The current pb is:
>- we have had difficulties separating what concerns the technology and
>what concerns the specification in GL 3, 4, and 7
>- some CP speak about entries in TOC, but it's not clear to which TOC
>these CP apply; in the case of profiles, this could be the "main" spec,
>a specific profile, the rules for profiles
>
>My view on this is that we are actually treating the same way 2 very
>different issues:
>- specifications defining one or more [modules,levels,profiles]
>- specifications "using" (that is, inheriting features defined by) one
>or more [modules, levels, profiles]
>
>The confusion between the 2 issues is easy to make since often, a
>specification matches this 2 categories (e.g. CSS TV Profile defines a
>profiles, using CSS Modules).
>
>A related issue that we don't clearly address but that we probably
>should is the question of subsetting a specification (does the spec
>allow it? if yes, under what rules? ...)
>
>I'll try to see if I can find a good way to match this in a new
>structure for GL 3, 4 and 7, but any comment in the meanwhile is
>welcomed :)
>
>Dom
>--
>Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
>W3C/INRIA
>mailto:dom@w3.org