If you are going to write WebDAV Standards - PLEASE READ THIS

One of the smartest things the WebDAV authors ever did was to listen to
Larry Masinter's suggestions
(http://lists.w3.org/Archives/Public/w3c-dist-auth/1997AprJun/0246.html)
regarding how to put together our early drafts. The way we implemented his
suggestion was to require that every feature in the spec have three
sections. 

Section 1 - A description of the problem the feature was meant to address

Section 2 - A proposed solution for the problem

Section 3 - An explanation of the design rational behind the solution.

If you look at the early drafts you will literally see things like:

PROPFIND -
	Section 1
	Section 2
	Section 3
COPY -
	Section 1
	Section 2
	Section 3
Etc.

Sections 1 & 3 do not belong in an RFC because they are not normative.
However, imagine how much more useful the WebDAV spec would be if we could
release an "unofficial" version with all the sections 1 & 3? In essence "The
WebDAV Book of Why" is just me trying to remember all the arguments we made
in the old section 3s. The section 1s were supposed to be covered by a
scenario document, but the draft died from lack of interest.

If I had it all over to do again I would use styles in Word to mark sections
1, 2 & 3s and then I would use Visual Basic for Office (or whatever it is
called) to write a program to auto-generate the "official" version only
consisting of section 2s.

My recommendation to WebDAV authors, especially the versioning group, is
that they seriously consider using this same structure for their drafts.
More than that, if they will be using Word, they should seriously consider
putting together the environment I propose. In one of those "you can pay me
now or you can pay me later" type of situations, you can put these sections
into the draft and maintain them or you can keep re-explaining yourselves on
the mailing list for years to come.

My penance for not putting together that environment is The WebDAV Book of
Why, which is 37 pages and counting. Please, save yourselves some serious
pain.

Received on Sunday, 14 February 1999 18:20:23 UTC