Subject: PaceReduceMustMay: new editorial proposal

From: Ken MacLeod <[email-masked]>
Date: 15 Jul 2004 18:25:43 -0500

This is the initial proposal for reducing the potentially unnecessary
use of RFC2119 imperatives in the Atom drafts.  I'm willing to do the
legwork of getting the proper "boilerplate" pattern from other RFCs
for specifying content models in a more readable and less formal tone,
and make those available to the editors.

I wanted to pause and make sure the WG and editors think this is a
necessary and useful thing before I do the legwork.  Please take a
quick scan of the RFC sections listed below for comparible usage.

  -- Ken

== Abstract ==

  The RFC2119 imperatives MUST, MUST NOT, MAY, and SHOULD are used
  extensively in the format and protocol drafts to describe XML
  content models, which is unnecessary.

== Status ==

  Open -- Editorial.

  Author: KenMacLeod

== Rationale ==

  The XML element content models within the Atom Internet Drafts are
  part of the "basic specification" of the Atom format and protocol,
  like the use of ABNF (RFC2234) in traditional RFCs.  It is
  unnecessary to use requirements imperatives for the cardinality or
  markup syntax except "where it is actually required for
  interoperation" (RFC2119, Sec 6).

  Example XML-based RFCs for comparison:

   * RFC3017 -- XML DTD for Roaming Access Phone Book. M. Riegel,
     G. Zorn. December 2000.

     http://www.ietf.org/rfc/rfc3017
     Sections 6.1 and 6.2.  Uses DTD syntax to describe content model.

   * RFC3275 -- (Extensible Markup Language) XML-Signature Syntax
     and Processing. D. Eastlake 3rd, J. Reagle, D. Solo. March 2002.

     http://www.ietf.org/rfc/rfc3275
     Section 4.  Uses XML Schema to describe content model.

   * RFC2518 -- HTTP Extensions for Distributed Authoring --
     WEBDAV. Y. Goland, E. Whitehead, A. Faizi, S. Carter,
     D. Jensen. February 1999.

     http://www.ietf.org/rfc/rfc2518
     Section 12.  Uses DTD syntax.

== Proposal ==

 1. First pass: de-emphasize RFC2119 imperatives where used for
    content models or markup syntax.

 2. Second pass: rephrase for easier reading using a less formal tone.

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 15 Jul 2004 22:25:57 -0700

Hi Ken.

I think it's fine to replace the normative requirements in prose with 
some sort of schema language -- if one can be agreed upon -- but I'd 
like to have the replacement in place before we rip these out. Would 
your proposal extend to that?

Also, I'm a little uncomfortable with editorial work by Pace; it smacks 
of word-smithing by committee, something that IME doesn't work out 
well. I'm happy to take suggestions on board, but having people propose 
editorial changes word-for-word to be incorporated wholesale removes 
the ability of the editors to make a judgement call.

That said, could you expand upon what you mean by reducing the 
formality of the specs? I would grant that the prose is a bit turgid 
now -- something that I planned to address in an upcoming edit -- but 
on the whole, I prefer to err on the side of formality.

In my experience, more formal specs, while requiring a bit more effort 
on the part of the reader, usually result in much tighter, 
interoperable, and more correct specs; OTOH the looser, more 
conversational specs that I've been involved with have always been the 
ones that different people interpret in different ways.

Put another way, the spec itself has a very specific audience -- 
implementers -- and they have very exacting requirements that demand 
formal description. Material for a wider audience (e.g., evangelism, 
user guides, advice in a vehicle like a primer) can and should be less 
formal and more flowing.

Cheers,

--
Mark Nottingham     http://www.mnot.net/

---

From: Ken MacLeod <[email-masked]>
Date: 16 Jul 2004 18:53:36 -0500

Mark Nottingham <[email-masked]> writes:

> I think it's fine to replace the normative requirements in prose
> with some sort of schema language -- if one can be agreed upon --
> but I'd like to have the replacement in place before we rip these
> out. Would your proposal extend to that?

The suggestion isn't specifically to replace the imperatives with
schema/BNF, but to remove the strong imperatives from what is basic
specification.  Example:

4.8  "atom:id" Element

   The "atom:id" element's content conveys a permanent, globally unique
   identifier for the feed.  It MUST NOT change over time, even if the
   feed is relocated.  atom:feed elements MAY contain an atom:id
   element, but MUST NOT contain more than one.  The content of this
   element, when present, MUST be a URI.

   xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to the
   atom:id element's content.

becomes:

4.8  "atom:id" Element

   The "atom:id" element's content conveys a permanent, globally
   unique identifier for the feed.  It MUST NOT change over time, even
   if the feed is relocated.  atom:id is optional and is not
   repeatable.  The content of this element is a URI.  xml:base
   processing is applied to the atom:id URI.

As a separate concern, having schema/BNF notation would be a good
thing.  The decision factor for using a schema language as a
*notation* is lower than the decision factor for having a normative
schema.  WebDAV, for example, uses DTD notation for speccing element
models but does not have a normative DTD (since that would restrict
Namespace usage and enforce insignificant element ordering).

> Also, I'm a little uncomfortable with editorial work by Pace; it
> smacks of word-smithing by committee, something that IME doesn't
> work out well. I'm happy to take suggestions on board, but having
> people propose editorial changes word-for-word to be incorporated
> wholesale removes the ability of the editors to make a judgement
> call.

My offer is to do the legwork on finding current common practice and
providing those to the editors to implement, not the word-by-word
editing.  Proposing a notation for content models would be in scope
for this pace.

> now -- something that I planned to address in an upcoming edit --
> but on the whole, I prefer to err on the side of formality.

> In my experience, more formal specs, while requiring a bit more
> effort on the part of the reader, usually result in much tighter,
> conversational specs that I've been involved with have always been
> the ones that different people interpret in different ways.

The above example isn't really conversational, it still has one
specification statement per sentence, but by removing the need to work
in a "MUST", "MUST NOT", etc., it can be more readable without being
less rigorous.

If you've already planned on doing something like this, then I'll go
ahead and stop here.  The discovery of using a schema as a notation
rather than a normative schema is good information, though, I think
I'll work up a suggestion/comparison there.

  -- Ken