- From: Lisa Dusseault <lisa@xythos.com>
- Date: Fri, 14 Feb 2003 09:25:09 -0800
- To: "'Julian Reschke'" <julian.reschke@gmx.de>, "'Webdav WG'" <w3c-dist-auth@w3c.org>
> > "(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