Re: SpecLite Outline

Le mer 17/03/2004 à 20:55, Lynne Rosenthal a écrit :
> Below is an outline for the new SpecLite. 

Short comment: Wow ! The outline is really very promising...
More detailed comments below.

> Question: what should be the normative, mandatory statements?  (section 
> titles or text within a section)?

As Lofton, I think text within a section is better for the normative
statements.

> **************************************************
> SpecLite Outline
> 
> Target Audience: Spec writers.

> 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.  Also, if someone is 
> in a hurry, this is what you want them to see and do)

Agreed. The intro verbiage should explain why conformance is so
important for a specification, to motivate its prime place in the
document.

> A.1. Include a conformance section   [8.4]

> A.2 Specify how to make conformance claims   [9.1]

This seems less important than A.1 ; the text should either make clear
our priorities in that regard, or we could even push that as an advanced
topic (given that W3C Specifications as of today more often contains
conformance sections than detailed conformance claims).

> B.  First things first

(needs a better title I think)

> B.1. Define the scope  [1.1, 1.2]
> Scope = purpose, goals, audience, applicability
> @@need to say how this is related to conformance.

Not only to conformance, but also how it helps keep focused on the goals
of the specification ; this section should be used as a point of
reference for Working Groups to evaluate when they start going too far
off their goals/charter.

> Good Practice: put in the beginning of the document (duh!)

Hmm... Do we need to put it as good practice? If it appears somewhere in
the verbiage, that's probably good enough.

> Good Practice: make it simple and understandable

Strike that ; this would apply to any text in the spec, I think.

> Good Practice: use examples, use cases to illustrate

(sounds good ; probably worth stressing the usefulness of use cases).

> 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.
> -What is the target of the spec  what will implement it
> -What will be the object of the conformance claim

Again, it'll be worth stressing that these questions can be used along
through the design of the specification (so that each time a new feature
is "created", it's brought in relations with a specific object of the
conformance claim, and it's reflected as such in the spec).

> B.3 Make a list of normative (and non-normative) references   [7.2, 7.3]

Needs to stress why it is important to distinguish between them.

> Good Practice:  start now and keep adding to it as you go.

Hmm... Maybe that's too obvious ?

> C.  Piece needed to Specify Conformance
> 
> C.1 Define your terms   [8.2, 8.5]
> 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

Also, relates to the conformance model (mandatory vs optional only
matters in a given framework).

> Examples: use RFC keywords, assertive voice, gold stars.
> 
> Good Practice: being able to find these requirements easily  navigation   [7.4]
> 
> D. Variability affects Interoperability
> 
> D.1 Dividing up the technology   [3.1]  @@ need a better title
> D.2 Being flexible  [5.1]
> D.3 Allowing extensions  [6.1, 6.2]

This needs to be related to the discussion in the TAG with regard to
versionning and extensibility.

> Good Practice: include a motivation for allowing extensions or restricting 
> (or prohibiting) their use

Not sure about this one...

> D.4 As specification evolves deal with deprecation [4.1]

> Good Practice: Include the reason for the deprecation [4.4]

Not sure about this one.

> E. End Game
> 
> E.1 Methodical review of the Spec
> Read it carefully, make sure everything is defined, all pieces are there, etc.
> 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

(let's not put QAWG review in the doc ; hopefully, our documents will
last laster longer than our WG :)

> Good Practice: write sample code, test cases

Maybe with an advanced topic on test driven development for
specification?

Thanks, really a great start!

Dom  
-- 
Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org