Re: Spec Guidelines

At 03:22 PM 3/8/02 +0900, Martin Duerst wrote:
>I'm not sure I agree. Pubrules are hard and fast rules;
>if you don't follow them, publication is rejected. It
>should be kept as short as possible.

Pubrules makes also reference to "How to Write a W3C Technical Report",

http://www.w3.org/Guide/Reports

which is considerably lengthier than pubrules itself.  It seems that the 
reference is normative -- "Editors and Team contacts should consult 'How to 
Write a W3C Technical Report' for detailed guidance." -- i.e., you have to 
do the stuff in "../Reports".  Is that correct?


>The style guide is on a different level. It tries to help
>editors, and contains many things that may be obvious to
>people who are used to technical writing, and many things
>that one could also do another way, and where it is good
>to have some help, but if somebody has good reasons, they
>should be able to do things somewhat differently. The
>style guide is already long, and can get longer.

It does do all of those things -- presenting lots of helpful information to 
editors -- but it also gathers together (subsumes?) the stuff in 
"../Reports" and also (I think) much of pubrules.  In doing so, it gets rid 
of all of the "@@" incompletions, such as "@@Not sure what this section is 
about..." and "@@In development@@" (in ../Reports), and is generally a more 
polished document.

So that is where the duplication is.  For my own (novice W3C editor) taste, 
the style guide is a nice reference for "one stop shopping" on editorial, 
pubrules, and style questions.  As Dom has pointed out, pubrules (and 
"../Reports) is the definitive normative source.  But that doesn't mean we 
couldn't evolve the style guide so that it had normative and informative 
sections, where the normative sections eventually replaced pubrules+Reports.

Regards,
-Lofton.


>Regards,   Martin.
>
>At 09:56 02/03/01 -0500, Dominique Hazael-Massieux wrote:
>>On Fri, Mar 01, 2002, Daniel Dardailler wrote:
>> > I don't think it's a good idea to have both
>> >   http://www.w3.org/Guide/pubrules
>> > as a subset of
>> >   http://www.w3.org/2001/06/manual/
>> >
>> > This duplication will lead to confusion.
>> >
>> > I think we should only carry forward the second one, the Manual of
>> > Style, using a checkpoint layout with priorities 1, 2, 3 (much like
>> > the WAI guidelines), and assign P1 to pubrules checkpoints, with a
>> > policy enforcing level A.
>>
>>That looks a  very reasonnable proposal. We'll have to think about the
>>process part of such a merge, since pubrules are a quite sensible
>>subject (changes must be approved by the team, announced to the chairs).
>>
>>Dom
>>--
>>Dominique Haza$BuM(B-Massieux - http://www.w3.org/People/Dom/
>>W3C's Webmaster
>>mailto:dom@w3.org
>

Received on Friday, 8 March 2002 11:07:43 UTC