Re: SpecGL Selling points

Here are a bunch of minor editorial suggestions.  Some of these I already 
mentioned in telecon today.

At 12:16 PM 11/12/03 -0500, Lynne Rosenthal wrote:
>[...]
>
>**********************************************************
>QA: take time now or pay later

Suggested section title:  "Quality -- invest now or pay later", or 
"Specification quality -- invest now or pay later"

Also ... we agreed to keep the following paragraph (below).  I'd suggest 
that it ought to be like a Preface or Foreword (maybe with some interesting 
offsetting CSS styling), and move the section title down after it.

Editorial suggestion (below):  change "quality-built guidelines" to 
"quality guidelines".  (Double entendre conveys the original meaning and 
another as well.)


>Quality is never achieved by chance... it is the result of endless 
>research, experience, skilled craftsmanship and the uncompromising 
>devotion to the ideal that quality is never out of style. W3C QA WG offers 
>the world's most complete line of quality-built guidelines...over three 
>models to choose from...each the leader in styling, performance and 
>value.(From http://www.radiophile.com/tomaqual.jpg)

(Move section title here.)


>FACT: Software development projects typically spend 40%-50% of their total 
>effort on avoidable rework.  CLAIM: Specification development also spends 
>a significant amount on avoidable rework.
>
>SpecGL
>·       It helps ensure ….
>·       It provides …
>·       It improves the readability, implementability, and testability of 
>the specification
>·       It shows …

Does "It" at the start of each bullet add anything?


>Different Stakeholders use of SpecGL:  (reflect their benefit, interest, 
>or need)

Suggestion:  "Different stakeholders benefit differently"  (and we agreed 
in telecon that we should find a better word than "stakeholders", for which 
I don't have a suggestion now.)

>·       For specification developers: early understanding of conformance 
>concepts, less rework or scrap, less burn-our of editors,

Ed: "burn-out"

>·       For implementers: helps to target areas of spec that are of 
>interest.  Don’t need to read entire spec  just the parts that you will 
>implement.  For example, if building a
>·       Test Developer.  Test Assertions are tagged, conformance is well 
>defined

"Identified" or "isolated" might be better than "tagged" (given what SpecGL 
actually requires).

>·       W3C member.  specs get developed faster, can implement sooner and 
>faster,
>·       W3C organization.  reputation enhanced, recommendations faster and 
>higher quality, reduced maintenance

Suggestion:  "faster, cheaper, and higher quality.

I volunteered to redraft the following (to make it more SpecGL-specific, 
and less general-QA "preaching to the choir").  I'll do that separately.


>QA is Important
>It may seem wacky to take precious time now, but integrating QA practices 
>into every step of the specification writing process will pay off.
>·       It is a well-established fact that the sooner a defect (e.g., 
>ambiguity, hole in the specification) is found the less expensive it is to 
>fix.
>·       Early QA lifecycle activities help increase the overall 
>effectiveness and efficiency of specification development.
>·       Early QA involvement allows evaluation of important planning, 
>design, and development decisions with respect to how these decisions aid 
>the testability of the specification.
>·       Continuous QA activities can reduce the amount of redrafting or 
>scraping text, the number comments to resolve, and the time to publication.
>
>Invest in QA and get to Recommendation faster by spending less time 
>rewriting the specification, by fostering the development of test 
>materials, and by facilitating the development of implementations.

Previous paragraph is redundant -- I think everything is said 
elsewhere.  Would anything be lost by deleting it?


>When do QA

We discussed a new title.  I like something along the lines of "How and 
when to use SpecGL".  But I can live with any of the suggestions, as long 
as we replace the generic and vague "QA" with the specific "SpecGL".

>Use SpecGL to develop a quality specification  that is useful to the 
>intended users and that is presented in an accurate, clear, complete and 
>unbiased manner. Each guideline contributes to improving the quality of 
>the final specification by leading you through a series of checkpoints.
>·       Use SpecGL in the beginning to get organized: think about the 
>scope, how the technology will be implemented, what needs to conform, ways 
>to subdivide the technology, and ways to allow variation among 
>implementations.
>·       Use SpecGL while writing the specification as a cheat sheet: to 
>make sure you haven’t forgotten something and for ideas on how to describe 
>something.
>·       Use SpecGL during document preparation as a guide to markup: to 
>aid in navigating the document, to indicate discretionary items, and to 
>call out requirements and test assertions.
>·       Use SpecGL at the end of the writing process to see if you missed 
>anything.

I suggest a new section title here.  Something like "It's easy", or "Making 
it easy", or ...

>The use of standardized approaches, frameworks, and tools can reduce the 
>costs associated with specification development.  Over time, we hope to 
>augment the Examples and Techniques with more tools, templates, and 
>examples to help you implement the SpecGL principles faster and/or more 
>easily.  We also plan to work with you, as you develop your 
>specifications, in applying the SpecGL.
>
>Evidence
>(examples of WGs experience in doing QA and/or using SpecGL - e.g., SVG, UAAG)

TBD.  But a comment:  we should choose carefully for the SpecGL 
context.  Different WGs have had different strengths in quality practices 
-- test suite development, exemplary specifications, interesting 
operational setup, etc.

-Lofton.