Clear specs: suggestions

[John E. Simpson]

It's been educational, not to say entertaining, to have read the firestorm
of opinion over the last week. (Ron Bourret's recent posts on suggestions
for clarifying the Namespaces in XML spec, and contrasting it with XML
1.0's, was especially well-done and much appreciated.) I thought of a
couple things the W3C might do to help ensure the quality of standards
*documents* (vs. the quality of the standards-behind-the-documents). Both
of these suggestions would apply only to documents at the WD or later stage
-- NOTEs would be exempt.

(1) Templates (or at least, guidelines): This seems so obvious that I can't
believe it's not already being done; a few comments in the last week imply,
however, that each WG sort of goes about the preparation of the document
with its own ideas, more or less, of what a spec should look like and how
much detail it should contain. I'm thinking here of DTDs for WDs, PRs, and
RECs. The content model for the WD level might contain elements like
"openissue" that would be absent from the latter two levels -- or relegated
to "for future consideration" appendices. I really liked the approach
suggested by Ron (I think; apologies if I'm either misattributing the idea
or misrepresenting Ron) -- formalism, narrative, examples. That suggests
the main content model for each topic and sub-topic in a spec.

(2) Establish editorial-review committees at least at the level of the
W3C's four "domains": User Interface, Technology & Society, Architecture,
and the Web Accessibility Initiative. (Depending on resource requirements
and availability, this might better be pushed down to the level of
individual activities within those domains.) Because these committees would
be familiar with the broad issues as well as, perhaps, some of the details,
but not involved at the nitty-gritty level of thinking of the spec writers,
I'd think they'd be good stand-ins for the target audience(s). In order not
to bog down the drafting process, a given spec's editorial review might be
required no sooner than the transition to PR, but definitely before
becoming a REC.

My apologies if I'm speaking out of turn here. I'm not a member (nor is my
employer) of the W3C; these just seemed to be two reasonable, non-onerous
approaches to ensuring clarity and consistency in published specs.

Best,
JES

=============================================================
John E. Simpson          | It's no disgrace t'be poor, 
simpson at polaris.net      | but it might as well be.
                         |            -- "Kin" Hubbard

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)