SpecGL review: GP use examples, use cases, and graphics

The following are comments by Richard

>-----Original Message-----
>From: Kennedy, Richard T
>Sent: Friday, October 22, 2004 3:34 PM
>To: 'Lynne Rosenthal'
>Subject: Re: Review of Draft
>
>Lynne,
>My comments follow in red. The text in braces explains the changes.
>Good Practice: Provide examples, use cases, and graphics
>What does this mean?
>Illustrate concepts, behaviors, functionality, interaction, etc. through 
>what ever whatever {per Merriam-Webster Dictionary whatever is the proper 
>form when used as an adjective} 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.? {Interrogative should end with question mark}
>It is difficult to understand some concepts, behaviors, functionality 
>other aspects of a specification without informative interpretations to 
>aid the reader. Some concepts, behaviors, functionality, or other aspects 
>of a specification are difficult to understand without informative 
>interpretations to aid the reader. {Original sentence is passive} 
>Providing the reader with additional information beyond the specification 
>s prose, {Superfluous comma} can only help in achieving implementation and 
>interoperability.
>
>Techniques:
>It is up to tThe Working Group to determines {Original sentence is 
>passive} 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. {The abbreviation for et 
>cetera should end with a period} that make sense.
>
>1. Develop use cases to illustrate the specification scope. Use an 
>{Missing indefinite article} 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 Iissue. {The word issue normally would not have an initial capital 
>letter. The sentence should end in a period}
>
>3. Provide an example to illustrate the meaning of abstract notations 
>(e.g., BNF). {The purpose of the text in the parentheses is unclear to me. 
>The sentence should end in a period}
>
>4. Provide an example for each chapter in the specification. {The sentence 
>should end in a period}
>5. Describes the language features through numerous examples and 
>compliment them by references to the normative texts. {The sentence should 
>end in a period}
>
>6. Reference a non-normative tutorial document which that {Proper use of 
>the reflective relative pronoun} includes informative explanation of 
>concepts, behavior, or functionality. {Is the term non-normative 
>understood by this document's audience or defined somewhere in the document?}
>
>7. Provide non-normative references to resources such as books, 
>specification annotation, and {Missing conjunction} test sets. These 
>references provide annotations to the specification, pictorial 
>illustrations, and explanations of specification rules. {Is the term 
>non-normative understood by this document's audience or defined somewhere 
>in the document?}
>
>Examples:
>For markup specifications, provide at least one example of each markup 
>construct.; i Illustrate each transformation capability with an example 
>showing input and output. {More readable if not a compound sentence}
>
>(Taken from Examples and Techniques 
><http://www.w3.org/QA/WG/2003/09/qaframe-spec-extech-20030912>http://www.w3.org/QA/WG/2003/09/qaframe-spec-extech-20030912) 
>{Missing closing parentheses}
>
>SVG. For each element of the SVG specification, you there will have be the 
>verbose definition of the element, the DTD definition, the attribute 
>definitions, {Per prior comment} and an example. For example, in the 
>definition of the element <http://www.w3.org/TR/SVG/shapes.html>rect, you 
>will find contains <http://www.w3.org/TR/SVG/shapes.html>precise examples 
>with the markup to generate the rect, a rendering of this markup as an 
>image to aid in its help people to visualizatione what it should be, and 
>an original version of the markup to test it as a separate file.  {Removed 
>2nd person references}
>
>HTML 4.01. The HTML 4.01 specification has been dDesigned in a to be very 
>educative, the HTML 4.01 specification way. It has strong caveats with 
>regards to the implement ability and the definition of testability. But by 
>Because of 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. When an example is given, 
>it is important to state whether the rendering of the example is 
>mandatory. {Reworded for clarity} Many developers try to mockup a rendered 
>example when a specific rendering is not mandatory. {I'm uncertain as to 
>the meaning and scope of this warning}
>
>When the HTML 4.01 specification defines the 
><http://www.w3.org/TR/1999/REC-html401-19991224/struct/text.html>elements 
>strong and 
><http://www.w3.org/TR/1999/REC-html401-19991224/struct/text.html>em and 
>gives examples of it them {Elements is plural}, it clearly says states 
>{Specification don't speak} 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 This example would have even been better to if it 
>mentioned that user agents should not assume specific rendering for these 
>elements. {Explain why it would have been better}
>
>As this is my first effort, did I provide you with useful feedback?
>
>Richard T. Kennedy
>Web Services Team
>Puget Sound Information Technology
>Boeing Information Technology
>The Boeing Company
>PO Box 3707 MC 42-77
>Seattle, WA 98124-2207
>206-662-2304