RE: Review of ordering draft, version 05

> >   "(DAV:ordering-type-set): the collection was created with the
> > specified ordering type. "
> 
> (that *is* a full sentence, isn't it?)

My suggestion isn't really about grammar, it's about readability.  This
is a passive phrase, which requires the reader to have a lot of context
and experience to understand what behavior is required of whom.  

> I agree that the condition itself can be expressed in a more stringent
> manner. However, I strongly disagree with the second sentence: all
> pre/postconditions are MUSTs (by definition), and therefore 
> the statement is
> (a) redundant and (b) - for consistency - it would have to be 
> repeated on
> each an every condition.

Yes, I agree that consistency helps make a spec readable.  What I'm
proposing is to put a phrase such as "the server MUST..." on each and
every condition. I will propose specific sentences if necessary, but I'm
not sure I even understand each postcondition (which is itself clearly a
problem).

The reason I suggest this redundancy is because I talk to a lot of
people who implement WebDAV yet who haven't read every word of every
spec.  I remember my first job working on WebDAV in 1998 and I just
browsed through the WebDAV and HTTP specs lightly. Then when a developer
would ask me a specific question about something like how range headers
worked, I'd look up that specific section. Usually, I could find the
answer without having to integrate massive amounts of text from various
sources, because in fact RFC2616 and RFC2518 are fairly well-written. 

Since this is the way specifications are used, a well-written
specification *does* have a lot of redundancy. In writing essays,
students are told to say what you're going to say, say it, and then say
what you said. A specification is not a piece of code, to be executed by
a computer which can load every line into memory and compile before
executing. It's a puzzle that's too big to be seen at once, so instead
each reader picks up a small piece of the puzzle at a time and tries to
understand some of the picture just from that piece. A pragmatic
approach to writing a successful specification takes that into account
and provides enough context in each puzzle piece so that piece makes
sense.

Lisa

Received on Friday, 14 February 2003 18:58:30 UTC