Re: QA Conformance Clause Template

At 02:32 PM 7/20/2005 -0400, Karl Dubost wrote:


>Le 05-07-20 à 11:41, Lofton Henderson a écrit :
>>>do you have news for the Conformance Clause Template?
>>>     http://www.w3.org/QA/2004/08/SpecGL-template-root.html
>>>Would you be able to throw it in the mailing list an outline of it if
>>>not yet completed.
>>
>>[...]
>
>>You are indeed pointing to the current version of the template,
>>which then points to two variations:
>>
>>[1] http://www.w3.org/QA/WG/2004/08/SpecGL-template-text.html
>>[2] http://www.w3.org/QA/WG/2004/08/qaire-3-field.html
>>
>>It has been my desire and intention to finish work on them.  But
>>best intentions sometimes get postponed because of lack of time.
>>What remains to be done is as follows:
>>
>>[1] is a you-edit, text (HTML) version.  It is mostly complete, but
>>has a couple of flagged questions.  It probably needs to be checked
>>for final alignment with SpecGL (are all of its bits okay for a
>>Conformance Clause, and is it missing any important bits).
>
>The [1] seems feasible in a reasonable time. Going through your
>questions list.

Perhaps I can make a new draft of it for discussion at f2f, with attention 
to the below details...



>* [Ed note. Adding div/class markup to this template is yet tbd.]
>     I will do.
>
>* [Ed note. TBD. Is it going to contain example links? It would
>probably help user complete the template item.]
>     Two solutions can be proposed. Either we link back to the
>appropriate section of SpecGL, or we add particular examples.
>Sometimes a simple link to a specification, will not be enough
>without explaining the example. I don't have strong opinions. Maybe
>the easier is to link to specGL when needed?

Yes, that's easier for sure, and there must be a link to SpecGL, the the 
RQ/GP that relates to the template item.  But if I think of trying to use 
such a template, I guess I would rather go straight to an example than 
jump-to-SpecGL-then-to-example.

In the balance, SpecGL link for examples might be best (link straight to 
the Examples section of the relevant RQ/GP.



>* Understanding your notation.
>     I'm not sure I have understood the blue boxes with this kind of
>information.
>
>        [Having a Conformance Clause like this satisfies
>      @@Pr/GPx.y;@@] [Quick examples: @@Example 1@@; @@Example 2@@;
>     @@Example 3@@] [@@Detailed examples & techniques.@@]
>
>     Could you give me a hint? Is it for us to find in SpecGL the
>related section.

Pr/GP means a link to SpecGL Requirement or Good Practice.

Quick examples:  (direct) link to example of how to do the item.

Detailed Examples & Tech:  I probably wrote this when we had a separate 
SpecET document.  Now it could be a link to the T&E sections of the 
relevant parts of SpecGL, and/or combine this and "Quick Examples".


>* Improving the layout and the CSS
>     I think we could give a bit more readability for the users, by
>really making obvious what they should do themselves. :) I volunteer
>to do that.

Okay.


>* Normative language.
>     - either RFC 2119
>         The keywords "MUST", "MUST NOT", "REQUIRED",
>         "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
>         "RECOMMENDED", "MAY", and "OPTIONAL" in this
>         document are to be interpreted as described
>         in RFC-2119 [RFC2119].
>     - other
>         What do you suggest here Lofton?
>         One of the technique in
>         http://www.w3.org/TR/qaframe-spec/#consistent-style-tech

In the interactive-form template, you'll see a list of 
possibilities:  RFC2119 keywords, imperative voice statements, markup & 
styling, labelling of sections and subsections, etc.


>* [Ed note. Might (or might not) want to get rid of CoP terminology
>and replace it w/ something more common. But it is a convenient
>handle for now.]
>     Not sure we have to get rid of the expression "class of
>products" it really depends of the examples given in the section here.

I now think we should keep CoP terminology.  This was at a time when there 
seemed to be some movement towards getting rid of the terminology.


>* Clarity for CoP.
>     In the template, you say "Each of the following subsections
>discusses and defines ". You meant "Each of the following subsections
>of FooML discusses and defines".

Right, more specifically I meant "...of this FooML Conformance Clause..."

>Is there a requirement to link back
>to the appropriate part of the specification or just a list of
>section is enough.

I don't object to a list of references, rather than having the text in the 
Conformance Clause.  But I think that it is better to put all CoP 
definition in one place, as SVG has done for example.


>* Could you talk a bit more about the section "Conformance
>Designations"?

A/AA/AAA, etc (more later, time for telecon now...)


>* Conformance Claims
>     Valid is fine.
>
>* ICS pro-forma
>     It will be optional :) it's already an optional Good Practice. :)
>
>
>>[2] is a sample of an interactive form to query the editor for
>>information, then generate a skeleton Conformance Clause.  It needs
>>to be finished, and I need to write the PHP processor to process
>>the form.  (There is a sample already, and if you fill in the 3- section 
>>form at [2] and 'Submit', you'll see the processed result.)
>
>Once [1] is done. It should not be too hard.

It is the most fun part, I discovered from making the 3-question sample 
form and its PHP processor.

-Lofton.

Received on Monday, 25 July 2005 15:00:48 UTC