SpecGL Review Assignment

Hi, everyone

I've reviewed Section 2.1 Good Practice C:  Provide Examples, Use Cases and 
Graphics.  The section read fairly well but I've made a few changes.  My 
re-written section is contained below:

Mark


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 illustrative content 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 implementability 
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 mock up 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.


****************************************************************
Mark Skall
Chief, Software Diagnostics and Conformance Testing Division
Information Technology Laboratory
National Institute of Standards and Technology (NIST)
100 Bureau Drive, Stop 8970
Gaithersburg, MD 20899-8970

Voice: 301-975-3262
Fax:   301-590-9174
Email: skall@nist.gov
****************************************************************