Re: [SpecGL Draft] E. Good Practice: Do a systematic and thorough review.

Hi Karl

All comments are editorial.

6 PM 7/13/2004, you wrote:
> Good Practice:
>         Do a systematic and thorough review.
>
> What does that mean?
>         Each part of a technology should be reviewed by the WG before 
> publication, but also during the editing phase. It will help the 
> Working Group to identify missing pieces, spelling mistakes, 
> ambiguities, dependencies. With a well defined review process inside 
> the Working Group, it should not be difficult to achieve this issue.

s/achieve this issue/accomplish this task/


> Why should I care?
>         When a Working Draft is published with incomplete or very 
> drafty section, the WG might receive a lot of

don't think 'drafty' is a word, but I like it.  You could say raw, 
unrefined, or unfinished.

> comments which will be have to be answered at best, and that will 
> still be in the final Recommendation
> document at worse. Catching early the mistakes will decrease the 
> number of comments and so time and resources to handle them.

Not sure what you are trying to get with respect to 'still be in the 
final Recommendation' - since as written, it is the comments that would 
still be in the final Recommendation.  How about this:
'When a Working Draft is published with incomplete or very raw 
sections, the WG might receive a lot of comments which will have to be 
answered at best or the incomplete text will go unnoticed and appear in 
the final Recommendation at worst.'

> Related:
>         Editor's Guide?
>         Maybe stuff in Style Guidelines
>
> Techniques:
>         1. Create a simple and light review process. Perhaps, 
> establish a team, where each person focuses on a different aspect of 
> the specification's correctness.
>         2. Organize at least one review cycle before publication (more 
> if you can)
>         3. Organize the review by topic and expertise. For example, 
> each person checks a different part of the specification or do it by 
> expertise - the grammarian checks for consistency, grammar, spelling, 
> readability, the test builder checks requirements for precision and 
> implementability, the conformant checks that conformance criteria 
> exists.
>
> Examples:
>         XHTML 1.0: If you submit a web page address to the W3C MarkUp 
> Validator, it could happen that the result page tells you that your 
> document is "Valid XHTML 1.0 Strict" and provides a link to the XHTML 
> 1.0 Recommendation. If you follow this link you will encounter a 
> problem: There is no definition of what it means for a document to be 
> identified as "Valid XHTML 1.0 Strict".
>
>         Work Method of RDF/OWL? Jeremy Carrol?
>         Templating method and review for SpecGL Lite?
I think we can document our own experience.
Specification Guidelines: A template was produced to guide SpecGL 
authors, ensuring that each principle and good practice was written 
consistently and addressed the same set of information.  Once a 
principle or good practice was written, the text was circulated to the 
entire WG for comments and at the same time, a specific member of the 
WG was assigned to review the text.  This ensured that at least someone 
in the WG had the reviewing responsibility and it would not fall 
through the cracks.


Multiple authors produced the Specification Guidelines, following a 
template



> --
> Karl Dubost - http://www.w3.org/People/karl/
> W3C Conformance Manager
> *** Be Strict To Be Cool ***
>

Received on Thursday, 15 July 2004 10:23:36 UTC