Re: QAH comments

Lynne,

Thanks for your comments.  Here are some answers and thoughts.  First, the 
references (current published version, and editor's draft):

[1] http://www.w3.org/TR/2004/WD-qa-handbook-20040830/
[2] http://www.w3.org/QA/Group/2004/10/QA-handbook-ed

I'll have a look at "Primer" comments tomorrow.  QAH replies embedded below...

At 11:06 AM 9/28/2004 -0400, Lynne Rosenthal wrote:
>Following are comments I have, now that I have read through the document.
>
>General
>1. What is the difference between Principle and Good Practice.

Well before SpecGL sorted out that Principle=normative and GP=informative, 
I incorporated PRs and GPs into QAH with these implications:  PR is an 
organizing or more general concept, GP is a specific (e.g., an actionable 
detail).

>Since there is no normative content, does it make a distinction between 
>these? It may be confusing to have non-normative Principles in QAH, when 
>SpecGL makes Principles normative.  If we keep these 2, there needs to be 
>an explanation.

I favor an explanation.

>Additionally, Section 1.4 says that the QAH ‘integrates quality assurance 
>techniques and good practices’  what is the relationship to 
>principles.  My recommendation is to make everything a good practice.

I like the distinction, and favor an explanation up front in QAH.  I don't 
think there is significant gain in trying for consistency between QAH and 
SpecGL, as long as each document is consistent and clear within itself.

For now, I have added this sentence to section 1.3 right after PRs and GPs 
are introduced, "Principles tend to be general or high level encapsulations 
of a given topic area, and good practices tend to be more low-level, 
actionable details."  If people disagree with this approach, then it should be


>2. Principle and GP statements are long and very descriptive.  Should we 
>make these short, declarative phrases?

I favor imperative (current style) over declarative.

Length:  there are 19 PRs and GPs.  Of these, about 12 are around one line 
or less (viewed in browser on my laptop).  Some of the remaining ones do 
involve multiple thoughts.  I have no objection to shortening, and would 
welcome specific suggestions (including what to do with material that is 
omitted when shortening a PR or GP.)


>3.  Inconsistencies with topics under Principles and GPs as well as 
>variation of topic names.  For example, some P and GPs only have 
>descriptive text, others have Why care and What does this mean.  Others 
>have Example, How can I do it, Related.  Others have How, What does this 
>mean and examples, and yet another has Success criteria.

Is this a suggestion that every PR and GP should have every one of a 
defined subset of sections?  In general, I don't like consistency for 
consistency's sake -- it gets very monotonous.

On the other hand, the same thing should be labelled the same in different 
sections -- the topic names should be consistent.  I'll try to make a pass 
a consistent names.

Generally, if I didn't have something useful to say under a heading, I 
omitted it.  For example, sometimes "what does it mean?" is too obvious to 
waste a section of text.  If there are any omissions where we have missed 
the opportunity to say something that *should* be said, and that would be 
useful, then we should add them -- (all) please propose them.

This might be a useful break-out exercise -- where are there omitted 
headings, where we have missed the opportunity to say something important?


>4. Confusion between terms and their relationships.
>Will readers be confused by our use of ‘test materials’ ‘quality-related 
>deliverables’ (I think test materials is a subset of this), ‘quality criteria’

I have already made a pass at removing vague language like "QA 
deliverables" (formerly, they were pink tagged in editor's draft).  I tried 
in each case to come up with something that made sense in context.  No 
doubt I missed the boat in some cases.  Specific suggestions for 
improvement are welcome.

This might be a useful break-out exercise -- where are there omitted 
headings, where we have missed the opportunity to say something important?


>5. Spell out ‘spec’

Okay.  (DONE in editor's draft).


>6.  With the current structure/format, it is very difficult to identify 
>and call-out specific GPs.

I agree that a labelling scheme is needed.  Two possibilities:

1.) numeric, like PR-1 thru PR-n and GP-1 thru GP-n.  Or the label block in 
each boxed section could be "Principle 1:", "Good Practice 7:".  Or ...?

2.) or descriptive, like the label blocks in the Stories.  E.g., 
"Principle:  early commitment", or "Good Practice:  build/buy decision"

#1 makes navigation easier, if you're trying to find a specific one and 
know its name/label.


>More specific comments (most are typo, grammar, minor changes)
>
>1.2 Why QAH
>/see 2.1 Specification editors/ - what is this referencing?  Remove.

The previous link is to a Wiki page.  The "see 2.1..." tells what part of 
the page I'm pointing to.  Wiki subsections have horrible addresses (ids), 
and we previously decided they were dangerous to reference.  So ... link to 
the whole page and then narrow it down descriptively.

>
>1.4 last sentence
>‘to completion and maintenance’ - what does this refer to?

I changed it to, "to completion and maintenance of the Working Group's 
deliverables."  Does that make it clearer?


>1.5 Other QAF resources
>add (planned) after [QAF-TEST]

Done.

>
>Section 2:
>GP: decide as soon as possible….
>/programme/ program/

Done.  (Hmmm... why doesn't the Eudora spell checker object to programme?)


>GP: Think about…
>Move this list of quality-related deliverables to earlier in this 
>section?  The first Principle, talks about quality-related deliverables.

If PR=general (organizing), and GP=specific (actionable), does that make 
the current placement acceptable?


>‘Test Materials are the most common quality-related deliverables’.  From 
>the list, what is not considered test materials? I can only find 1 
>item.  Should we label items in the list or mention this fact?

Your point is well taken.  These bits could use a little work.  The 
TM-emphasis was added for resolution of a couple of Jeremy's key comments.

>GP: Put some thought into how…
>How can I do it?
>/to write it into the charter/to write into the charter/
>/for each and every of the above/for each and every one of the above/
>/groups life/group’s life/
>/TA/test assertion/

All fixed, thanks.


>Section 3
>GP: Put all of the Working Group’s important test…
>How can I do it?
>/There is not really/There really is not/
>Reorder these paragraphs.  Move What does it mean ahead of How can I do 
>it.  This way, Examples directly follow the last para of How can I do it, 
>which mentions examples.

Done.


>GP Identify a Working Group point-of-contact …
>/about/for/

Fixed.

>Example  this is identical to what is in the previous GP.  Either delete 
>or put in an applicable example

Noted with a placeholder in the text, and left TBD.


>GP: Specify an archived email list…
>1st para specifies a ‘.. separate from the Working…’  Why must it be a 
>separate list?  A WG may want to use their general WG mail list.

I'm not aware of any W3C WGs whose primary WG list is public 
writeable.  For example, QAWG is public readable, but not public 
writeable.  The key word is "public".  Most groups have separate lists for 
taking input from the public.


>GP Identify Web page(s) ...
>/actually// (remove)

Done.


>Paragraph: The Working Group’s QA Process Document is also…
>This is out of place here.  Needs to move somewhere else  perhaps Section 4?

Noted with an in-line TBD note.  Will look more carefully later.


>Section 3.2
>/development process are going/development process that are going/

Fixed.


>Section 5
>The term ‘test suite manager’ is introduced.  Is this the same as the QA 
>point of contact?    Do we need to explain what we mean by test suite 
>manager or is this understood?

Noted with an in-line TBD note.  Will look more carefully later.  Probably 
does need some coordination with "QA PoC".  We left this a little rough in 
the Santa Clara discussion.

Thanks!

-Lofton.