Re: TOC checkpoints

At 08:16 PM 10/25/2002 -0400, Lynne Rosenthal wrote:
>After some thought - I believe that the "Include a TOC" checkpoints are 
>really techniques and not a checkpoint.  The goal is:
>LH>Our goal is this:  it should be easy for the user to find all of the
>LH>information necessary to understand the conformance policy and all of
>LH>its details, regardless of spec partitioning.
>
>and the checkpoint should reflect this.
>
>I also agree with lofton's
>LH>I have been thinking whether we could unify all of these somehow...
>
>So, I would like to see 1 checkpoint that captures the goal and have that 
>checkpoint in 1 place.

I would like to see a specific draft proposal:  the checkpoint wording, in 
which guideline the checkpoint resides, its fulfillment criteria, 
discussion and rationale, and an indication of what might be in Extech.  (I 
can't volunteer for a proposed draft right now -- I have Intro and OpsGL/ET 
to edit now.)

What makes this difficult is making the "easy" testable, as Alex pointed 
out in a reply.  David's message in this thread [1] also contains some 
interesting statements of what should be possible -- test criteria, if you 
will -- with an acceptable TOC or equivalent navigation mechanism.

One way to quantify "easy" might be in terms of navigation jumps.  Some say 
that you ought to be able to reach any critical information in one or two 
jumps from the cover page (which is where you usually find the TOC in W3C 
documents.)  [Linked from the same navigation root as the functionality of 
the technical specification, and reachable by a navigation path no longer 
than the most direct path to any technical functionality.]

Although I agree that TOC is a technique ... on the other hand, can anyone 
think of any other techniques that are used in W3C "specs" (which, 
according to our new Scope & Goals, are specifically:  W3C Technical 
Reports)?  Can you point to "mature" /TR/ documents that don't have TOC 
(I'm sure there are some, but I don't recall any specifically).  If "no", 
then perhaps it isn't so urgent to genericize the navigation 
mechanism.  I.e., for now, we could leave the requirement stated in terms 
of TOC, but indicate that an equivalently "direct" (number of navigation 
jumps) navigation mechanism would constitute fulfillment.


Bottom line ... if there is a specific proposal that sorts this out, I 
would support it for 6-nov.  Else I would support reworking it for next 
draft after publication.  (The requirement is not bad now, it's just 
repetitive, and perhaps a little lacking in generality.)

-Lofton.

[1] http://lists.w3.org/Archives/Public/www-qa-wg/2002Oct/0129.html

>  This eliminates the need to repeat the checkpoint in every DoV-related 
> section, it ensures that any non-DoV items that could affect the 
> conformance policy would also be covered by the checkpoint, and we don't 
> need to worry about specs that may not have a TOC.
>
>regards
>Lynne
>
>To: &References="www-qa-wg@w3.org
>Message-ID: <OFD9237533.F87D0959-ON85256C5D.005F92F9@lotus.com>
>From: David Marston/Cambridge/IBM <&References="david_marston@us.ibm.com>
>Date: Fri, 25 Oct 2002 13:51:30 -0400
>Subject: Re: TOC checkpoints
>
>
>LH>A TOC entry is required for each of checkpoints 3.1, 4.1, 5.1, 7.5,
>LH>8.5, 9.7, 10.10 (note numbering problem).
>
>Numbering note: GL 6 is one of the DoV, but its TOC requirement is
>expressed in GL 10.
>
>LH>Our goal is this:  it should be easy for the user to find all of the
>LH>information necessary to understand the conformance policy and all of
>LH>its details, regardless of spec partitioning.
>
>...or navigation mechanism, as LH later mentions...
>
>LH>I have been thinking whether we could unify all of these somehow...
>
>That seems cleaner, but it revives the "negative mention" issue. The
>problem can be solved, but I gather that the sentiment is to be less
>strident about the requirement.
>
>Here's a restatement of what I, as a Quality Engineer, would want:
>Given a spec document, I should be able to
>(1) identify and retrieve all the other normative documents that
>     have bearing on this spec, then
>(2) identify a TOC or other navigation mechanism that allows me to
>     locate either
>(3A) the conformance section [Ck 10.9 satisfied] or at least
>(3B) the conformance clause [Ck 10.8 satisfied],
>and from that conformance material
>(4) either read or navigate to all the material about conformance
>     variability. For *each* of the 8 DoV, I should be able to
>     determine unambiguously either
>(5A) that the dimension allows no variability, or
>(5B) the extent of the allowed variability.
>
>Of course, (5A) could be satisfied unambiguously without a negative
>statement if the conformance clause/section has a statement of the
>form: "The only ways in which implementations are allowed to vary
>from one another are..." and then goes on to mention those DoV that
>are used.
>
>Is "unambiguous" more precise than "clear"? If not, we need specs on
>the comprehension capabilities of the "intended readers" of W3C
>Technical Reports.
>.................David Marston