SpecGL B1 Scope

B. Nature of the Specification – need a better title
Suggest:  Setting up Groundrules

1.  P1: Define the scope
-Technique
#2.  Make ‘Scope’ an item in the table of contents.

-Examples:
Suggest:  Many W3C specifications have included scope prose in the Abstract 
section.  We advocate making the scope a separate section in the body of 
the specification, making it easy to find and insuring that it is an item 
in the table of contents.

2.  GP Write simple, direct statements in the scope
-Why care
s/This one of/This is one of/

3. GP Use examples or use cases to illustrate
Suggest:  Good Practice: Provide examples, use cases, and graphics
What does this mean?
Illustrate concepts, behaviors, functionality, interaction, etc. through 
what ever means makes sense, such as examples, use cases, graphics, and 
sample code. This aids in the understanding of the specification, 
especially for areas that are innately complex or for which the Working 
Group has had to explain to its members or the public.  Additionally, a set 
of broad examples and use cases can help to clarify the specification’s scope.
Why care.
It is difficult to understand some concepts, behaviors, functionality or 
other aspects of a specification without informative interpretations to aid 
the reader. Providing the reader with additional information beyond the 
specification’s prose, can only help in achieving implementation and 
interoperability.
Techniques:
It is up to the Working Group to determine the best way to illustrate the 
scope and other parts of the specification. Typically, the nature of the 
specification will influence the type of examples, uses cases, graphics, 
etc that make sense.
1.  Develop use cases to illustrate the specification scope.  Use 
easy-to-understand narrative to describe situations that are applicable to 
the specification.
2. Provide an example for each behavior or functionality that was resolved 
from an Issue
3. Provide an example to illustrate the meaning of abstract notations 
(e.g., BNF)
4. Provide an example for each chapter in the specification
5. Describes the language features through numerous examples and compliment 
them by references to the normative texts
6. Reference a non-normative tutorial document which includes informative 
explanation of concepts, behavior, or functionality.
7. Provide non-normative references to resources such as books, 
specification annotation, test sets. These references provide annotations 
to the specification, pictorial illustrations, and explanations of 
specification rules.
Examples:
For markup specifications, provide at least one example of each markup 
construct; illustrate each transformation capability with an example 
showing input and output.
(Taken from Examples and Techniques
http://www.w3.org/QA/WG/2003/09/qaframe-spec-extech-20030912
- SVG. For each element of the SVG specification, you will have the verbose 
definition of the element, the DTD definition, the attribute definitions 
and an example. For example, in the definition of the element 
<http://www.w3.org/TR/SVG/shapes.html#RectElement>rect, you will find 
<http://www.w3.org/TR/SVG/shapes.html#ExampleRect01>precise examples with 
the markup to generate the rect, a rendering of this markup as an image to 
help people to visualize what it should be and an original version of the 
markup to test it as a separate file.
- HTML 4.01. The HTML 4.01 specification has been designed in a very 
educative way. It has strong caveats with regards to the implement ability 
and the definition of testability. But by its design, the specification has 
very good examples. An important thing that you must say when you give an 
example is whether or not the rendering of the example is mandatory. Many 
developers try to mockup a rendered example when a specific rendering is 
not mandatory.
- When HTML 4.01 defines the 
<http://www.w3.org/TR/1999/REC-html401-19991224/struct/text.html#h-9.2.1>elements 
strong and em and gives examples of it, it clearly says that The 
presentation of phrase elements depends on the user agent. Generally, 
visual user agents present EM text in italics and STRONG text in bold font. 
Speech synthesizer user agents may change the synthesis parameters, such as 
volume, pitch and rate accordingly. It would have even been better to 
mention that user agents should not assume specific rendering for these 
elements.