my TOC drafting assignment.

Dom (and others) --

Here is my drafting assignment.  There are three sections:  Lynne's 
original draft for the new "amalgamated TOC" checkpoint; my new draft, 
restoring the minimal list to normativity; change notes, highlighting what 
I did and why.


1.) LR proposed draft:
=====

Checkpoint:  Provide a way to find conformance information

To fulfill this checkpoint, a specification MUST provide at least one 
navigation mechanism that allows the reader to locate all 
conformance-related information in the specification.

Rationale: A reader must be able to easily identify and locate all the 
information necessary to understand the conformance policy and related 
conformance information without having to read the document from cover to 
cover.  Conformance information includes: the conformance section, 
conformance clause, and material about conformance variability.  A table of 
contents entry is one way to accomplish this.

2.) Revised draft:
=====

Checkpoint 13.4:  Provide a fast way to find conformance information

To fulfill this checkpoint, a specification MUST provide at least one 
navigation mechanism that allows the reader to locate all 
conformance-related information that is relevant to the specification.  The 
mechanism MUST minimally locate:  the conformance clause; any conformance 
section; unambiguous statements about those DoV that the specification 
employs, from amongst the eight defined in this specification; and 
requirements for conformance claims.

[Ed note.  Bullet list might be nicer for the latter.]

Rationale: A reader must be able to easily identify and locate all the 
information necessary to understand the conformance policy and related 
conformance information without having to read the document from cover to 
cover.  A table of contents entry is one way to accomplish this.  In 
addition to the minimal required set above, other conformance related 
information such as the ICS, location of test suites, etc, may be helpful 
to users and implementers.

3.) Change notes
=====

a.)  I added "fast" to the title.  I agreed with Alex's comment on the IG 
list.  No one has yet objected on that thread.  If you think this is 
unwarranted, you can remove it.

b.)  In the "to fulfill", I changed the final "in the specification" to 
"that is relevant to the specification".  It was a part of the previous 
(consensus) email and telecon discussion that all conformance bits that are 
relevant to the functionality of a document/specification must be findable, 
regardless of how the specification is partitioned.

c.)  In the "To fulfill", I added a required minimal set that includes 
exactly those things that we required in TOC before consolidating the TOC 
checkpoints into this one -- no more, no less.  This leaves the 
functionality unchanged.

d.) I added a last sentence to Rationale, including some other 
possibilities in addition to the minimal list.  These have been mentioned 
in the email, but I didn't add them to the minimal list because that would 
have changed the functionality from before.  (Toss the last sentence if you 
think this is unwarranted.)

-Lofton.

Received on Monday, 4 November 2002 14:04:35 UTC