Re: SpecLite Outline

Nice work!

Here are a few comments...

At 02:55 PM 3/17/04 -0500, Lynne Rosenthal wrote:

>Below is an outline for the new SpecLite.  You will notice that it isn't 
>short

IMO, the overall scope of topics covered is about right.  I can't think of 
any topics that obviously should be eliminated, or other ones that 
obviously should be added.

>and we may want to delete some of what I called Good Practice (i.e., 
>things that we would recommend) and other things.  In fact, some of these 
>may be obvious,

I think a couple are (and noted them in-line).

>may appear in a different format (e.g., within an example or description), 
>etc.

Question.  Are we going to abandon SpecET as a formal, separate 
document?  Roll its good stuff into here (with maybe some external 
template(s))?

>Additionally, the naming of section headings need work.
>
>Question: what should be the normative, mandatory statements?  (section 
>titles or text within a section)?

I favor a statement in the text, which is set off by boxing or styling or 
whatever (similar to WebArch or WCAG).

Question.  In the outline, what do we intend to be our "normative" 
statements?  I.e., can we enumerate them at this time, and approximately 
how many are there?


>**************************************************
>SpecLite Outline
>
>Target Audience: Spec writers.
>
>Notes on how to read this:
>   X (a letter) denotes a heading
>   X.# denotes a requirement   (@@ not sure if this should be the requirement)
>   Good Practice: is a suggestion, recommendation, a darn good idea
>   Advanced Topic: for those wanting more info, a link to more in depth 
> discussion
>   [#.#] relate to the relevant checkpoint
>   @@ comments
>
>A. Specifying Conformance
>(@@ this section could actually be at the end of the document.  I like it 
>here, since it provides a roadmap of things to come.

Opinion.  I found it a bit awkward to get a grasp on this section, with the 
forward references.  I see the point about the roadmap.  Maybe a good 
compromise would be:  have a concise informative roadmap up front, that 
gives a view of the SpecLite from 10,000', and emphasizes the central 
importance of an all-inclusive conformance clause.  Then that frees this 
section to be where it fits most naturally (TBD).

About contents of conformance section.  The rest of section "A" 
mentions:  B.2, C.2, C.3, D.1.  I think that an ideal conformance clause 
contains almost everything except Scope (B1) and End Game (E1).  I.e., it 
would have something for C1, D2, D3, D4, as well as the items that are 
currently mentioned.  I'm not sure how to work this into "A".

>Also, if someone is in a hurry, this is what you want them to see and do)

If they are in a hurry, we should give them a CC template that leads them 
through 90% of what we think they should do.  ("We never read the spec, we 
just started implementing the test cases.")  [1] is nowhere near clean or 
simple enough.  But if you go through it, it contains about a dozen places 
for them to do something, and would cover >90% of the outline.


>A.1. Include a conformance section   [8.4]
>Everything you need to know about conformance to FooML is here:  It contains:
>*Conformance model:
>--- specifying what may conform and how    (see B.2)
>--- any designations or concepts used to categorize conformance (e.g., 
>profile, modules) (see. D.1)
>--- ways that conforming implementations can vary from each other (see X.#)
>* how to find normative sections (see C.2)
>* how normative language is expressed (see C.3)

Okay, here's were we have 4 forward references for CC content.  Whereas I 
think we need to express in the section, "the more applicable stuff you put 
in one place into the CC, the better it is."   (A good practice?).


>A.2 Specify how to make conformance claims   [9.1]
>Provide the wording
>Include for consideration: the meaning/value of a conformance claim may 
>change as the spec and tests evolve.

Issue.  It does?  It seems to me that a well-formed (or valid?) conformance 
claim is invariant over time.  I.e., a proper instance of a conformance 
claim is tied unambiguously to a particular spec version, edition, errata 
level, etc.  And if there is a tie-in to tests (or ICS), then that is 
invariant also.  (Am I misunderstanding the point of the statement above?)


>Good Practice: conformance disclaimer   [9.2]

Toss!  (We decided in one of the SpecGL TAs telecons that it was nonsense 
-- no one could figure out what it means in the SpecGL context -- and we 
were going to get rid of it.)

>Good Practice (for some): provide ICS [9.4]
>Good Practice (for some): require ICS for the claim [9.5]
>
>B.  First things first
>
>B.1. Define the scope  [1.1, 1.2]
>Scope = purpose, goals, audience, applicability
>@@need to say how this is related to conformance.

As in, "CoP" might be used to illustrate scope or help define it?  (I'm 
using "CoP" for shorthand, not recommending that it


>Good Practice: put in the beginning of the document (duh!)
>Good Practice: make it simple and understandable
>Good Practice: use examples, use cases to illustrate
>Good Practice: point out what is not included (not in scope)
>
>B.2 What needs to conform    [2.1]
>@@Here are different ways to say basically the same thing.

Comment.  I'm not sure if all of our audience would agree with that last 
statement (about the next two).  E.g., think of the discussions we have had 
with OWL -- didn't they expect a lot of stuff to implement it, but they 
have no conformance requirements aimed at implementations?)

>-What is the target of the spec  what will implement it
>-What will be the object of the conformance claim
>
>Foo defines conformance for:   (fill in the rest)
>
>Examples of 'what': protocol, API, content
>
>Advanced Topic:  Classes of Product, DoV
>
>
>B.3 Make a list of normative (and non-normative) references   [7.2, 7.3]
>Good Practice:  start now and keep adding to it as you go.

This might be a case of "obvious".



>C.  Piece needed to Specify Conformance
>
>C.1 Define your terms   [8.2, 8.5]
>Define conformance concepts, designations
>
>Examples: valid, well-formed, foo-conformant, document conformance (CC/PP) 
>consumer conformance (CC/PP)
>
>Good Practice: being consistent and using the same term when you mean the 
>same thing  don't be a thesaurus. [7,3]

Question.  Do we mean this to apply to conformance language, or all 
language?  I think we should focus on conformance language (and could 
mention "all language" in passing -- or point to Manual of Style [is it in 
there?]).


>C.2 Identify normative and informative parts [7.2]
>Distinguish between normative and non-nomative content
>
>C.3 What is mandatory  [7.1]
>Indicate what requirements are mandatory as opposed to optional, 
>recommended, good ideas, etc.
>Expressions that conveys the criteria to be fulfilled in an implementation 
>of the specification
>
>Examples: use RFC keywords, assertive voice, gold stars.

Comment.  I'm thinking that C.3 & C.2 might need a little re-working, but I 
don't have a concrete suggestion.  For example, RFC keywords allow "degrees 
of manditoriness", which is the subject of C3, but "assertive voice" 
typically doesn't.  I guess "gold stars" would also -- *** = MUST, ** = 
SHOULD, * = MAY.


>Good Practice: being able to find these requirements 
>easily  navigation   [7.4]

Comment.  The previous stuff seems to be about the language used for 
individual, detailed testable statements.  At least, that's where the old 
RFC2119 checkpoint applied.  If you go and look at CP7.4 (near [2]), the 
"easy to find" (navigation) requirement is pretty specifically about some 
high level collective stuff, like the CC itself, the DoV discussion, 
etc.  So we're morphing the meaning of 7.4 here.  (I support being able to 
find everything easily, it's just a comment that this is not exactly what 
old-7.4 was about, I guess.)


>D. Variability affects Interoperability
>
>D.1 Dividing up the technology   [3.1]  @@ need a better title
>Subdivide into related groups of conformance requirements
>Examples: modules, levels, profiles
>
>@@ not sure what  to do with these questions, they lead you to doing the 
>right thing.
>- What are the division?
>- What are the ways conforming implementations differ?
>- How does an implementation conform to the subdivision?
>- Are there mandatory conditions or constraints  [3.4]
>
>Examples of reasons to divide:
>-- no one will implement the whole spec  easier to implement a subset
>-- incremental functionality
>-- target specific a type of device (SVG tiny)
>-- target specific audience
>
>D.2 Being flexible  [5.1]

Hmmm... it's probably because I'm biased against abuse of discretionary 
items, but "Being flexible" sounds too positive -- who could possibly 
object to "be flexible"?  (Sorry, no better suggestion right now.)

>Grants of discretions by the specification - discretionary items
>Allowing choices, options, implementation dependency
>
>Good Practice: being able to find these discretionary 
>items   navigation   [7.4]
>
>D.3 Allowing extensions  [6.1, 6.2]
>What are the conditions for extensions
>  where, when can they be used?
>- are there any constraints on their use (limitations)
>- prohibit their use from breaking the spec

Either above or below, "relationship to conformance [or conf. claims]" is a 
key item that should be expressed.


>Good Practice: include a motivation for allowing extensions or restricting 
>(or prohibiting) their use
>Good Practice: provide a uniform way to define that extensibility is being 
>invoked  [6.3]
>
>D.4 As specification evolves deal with deprecation [4.1]
>List deprecated features
>What is the affect on conformance  past claims, current, future -

I'm not sure what is meant by "past claims, current, future".   I think 
specs *do* need to say how the conformance of each "CoP" (pardon the 
shorthand) is affected for each deprecated item.  Is that what we're 
getting at here?  (Implementations conforming to current version of spec 
must have this-or-that behavior regarding stuff from previous versions that 
is being deprecated by current version.)

>(if applicable) give frames for when it goes into effect
>
>Good Practice: Include the reason for the deprecation [4.4]

If we think SpecLite is too big, and if we feel the need to pare it down 
further, then these "why?" items might be candidates (the other example was 
above, under Extensibility).

>Good Practice: Indicate workaround, how to avoid using  give examples [4.5]
>Good Practice: Do the same for obsolete features [4.6]
>
>E. End Game

How about "Quality Control".  That's really what we're talking about -- 
have some good quality control processes that you apply to the spec.

>E.1 Methodical review of the Spec
>Read it carefully, make sure everything is defined, all pieces are there, etc.

Obvious?  More to the point, having the authors read it is relatively low 
value.  I think this is what you meant, as expressed by 2nd Good Practice 
below?

>Do a thorough QA review of the document - to find inconsistencies, 
>ambiguities, etc.
>
>Good Practice:  create Test Assertions [10.1, 10.2]
>Good Practice: have someone else (external) to read it, ask QAWG to review
>Good Practice: write sample code, test cases
>------
>Comments welcome.

All for now,
-Lofton.

[1] http://www.w3.org/QA/WG/2004/03/SpecLite-template.html
[2] 
http://www.w3.org/TR/2003/CR-qaframe-spec-20031110/guidelines-chapter#Gd-support-conventions