proposal for new editorial practice

Forgive me for cross posting this, but I'm not too sure how much traffic
either of these lists gets these days.

I've been noticing that the documents written under the W3C auspices
seem to have a wide range of writing styles.  This can be a barrier to
comprehension. Most documents contain certain semantics that are common
to all, but the syntax to represent the semantics is different.  I would
like to suggest that a simple syntax be written up that writers of
documents can use to represent the meaning of their documents in a
clean, standard way; something like
http://www.w3.org/TR/2000/REC-xml-20001006#sec-notation and
http://www.w3.org/TR/2000/REC-xml-20001006#sec-terminology combined,
possibly with other additions as well.    

I'm proposing this because of a few problems that I have had in
understanding some of the specifications; their meanings were unclear
enough that without outside help I would have written code that was
disastrously out of spec.  The RFC series had this problem for a time
but have corrected this by publishing documents on how to publish
documents ( ftp://ftp.rfc-editor.org/in-notes/rfc2223.txt ,
http://www.faqs.org/rfcs/rfc2234.html among others) which to a large
degree corrected this problem.  Although their specifications appear to
me to be somewhat out of date (you are required to submit documents in
plain ASCII text, among other problems), if we had something like this,
it would help a great deal determining the meaning of some of the
specifications that have been and will be written.

Thank you for your thoughtful consideration,
Cem Karan

Received on Thursday, 1 February 2001 16:38:18 UTC