Spec purpose and organization.

[Gary P Cole <Gary.P.Cole@Sun.COM>]

Whatever organizing principle we choose, we should consider explaining 
it in the spec itself.
For example, even with the current organization, I'm thinking of 
elevating Concepts to the same outline level as Protocol Description and 
Schema Reference.  Concepts would still be a short section (and would 
still be a top-to-bottom read).  This would make the Introduction 
section shorter, and leave room for brief Purpose and Organization 
sections.  Purpose might be just one paragraph.  Organization would 
explain something like what follows.

The body of this specification is organized into three major sections: 
Concepts, Protocol Description, and Schema Reference. 
o  The Concepts section is written as narrative text and is intended to 
be read (or scanned) top-to-bottom.  Subsections highlight significant 
features. 
o  The Protocol Description section presents an overview of protocol 
features and then presents the purpose and behavior of each protocol 
operation.  The core operations are presented in an order that allows 
the examples to have a continuous and logical flow.  Subsequent sections 
present optional operations that are associated with specific capabilities.
o The Schema Reference section is an alphabetical index of schema 
entities: types, elements and attributes.  For each schema entity, a 
sub-section describes the purpose of the schema entity and where it is 
used.  Each schema entity section also contains a normative Syntax 
sub-section that describes the formal requirements for that entity.

The PSTC intends this specification to meet the needs of several 
audiences.  One group of readers simply seeks to answer the question: 
"What is SPML (and what sort of things does this specification actually 
define)?".  A reader of this type should expect to:
- read the Concepts section thoroughly
- scan the Protocol Description section
- scan (at least the outline of) the Schema Reference section.

Another group of readers will want to know: "How would I use SPML?"  A 
reader of this type should:
- read the Concepts section thoroughly
- read the Protocol Description section (with special attention to the 
purpose and examples)
- scan the Schema Reference section

A third group of readers will want to know: "How must I implement 
SPML?"  A reader of this type must:
- read the Concepts section
- read the Protocol Description section (with special attention to the 
Request and Response behavior sections)
- read the Schema Reference section (with special attention to the 
Syntax sub-sections)