RE: Deleting versions

"Lisa Dusseault" <lisa@xythos.com> wrote:
>
> > What can I add?  They are an integral part of the specification and
should
> > be read carefully and understood.  At least for me, the layout
> > and style do
> > not imply that pre/post-conditions may be glossed over or ignored.  In
> > fact, I find it useful to have the conditions stated explicitly in this
> > way, and _named_ for easy reference.
>
> It's not that your convention is not useful, it's that it's not normal.
> It's not how RFC2518 is laid out, for example -- none of the sections on
> error codes have contained normative stuff on how to _successfully_
complete
> the request.  We've all be trained by the other RFCs we've read to skip
over
> the error code sections at first read, and only refer when somethings
gone
> wrong. So of course one approach is to reorganize the way readers expect
to
> see it, putting requirements in the main text and simply listing the
codes
> later.

The pre- and post- conditions are not "error code sections".  They are an
integral part of the specification.  Furthermore, each condition is
individually stated in its own paragraph so you don't have to disentangle
them from the prose, and as a bonus the conditions are _named_ so that we
can talk about the <DAV:version-history-is-tree> precondition and know what
we mean without having to recount the entire description.  I think this is
very important and very productive (an analogy with pattern languages
springs to mind).  As an added bonus, these names are to be returned by the
server so that clients can determine why some operations failed!

> Since people don't read introductions, and they certainly don't remember
> introductory material if it doesn't refer to something they have seen
> already, you could recap the explanation the first time the
"precondition"
> and "postcondition" are mentioned.

Delta-V's conditions sections are not the same as RFC2518's Status Codes
sections.
I'd much rather have the conditions set out like this than have to mark-up
the document with each condition as you come across it in the general
description.

> Another approach is to replace passive voice in those section with active
> voice: "client MUST ensure..." and "server MUST"

This is good practice anyway.

Tim

Received on Wednesday, 6 June 2001 06:01:45 UTC