SpecLite Outline

Below is an outline for the new SpecLite.  You will notice that it isn't 
short 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, may appear in a different format (e.g., within an example 
or description), etc.   Additionally, the naming of section headings need 
work.

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

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

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)

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.

Good Practice: conformance disclaimer   [9.2]
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.

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.
-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.


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]

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.

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
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]
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

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 - (if 
applicable) give frames for when it goes into effect

Good Practice: Include the reason for the deprecation [4.4]
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

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
Good Practice: write sample code, test cases


------
Comments welcome.

Lynne

Received on Wednesday, 17 March 2004 14:56:36 UTC