Specification Guidelines

While the current draft of the specification was hugely better than earlier
versions, it still seems to me that some discussion of what makes a good
spec would be helpful.  We got some suggestions at the Irvine meeting:

        - If we specify more than one way to accomplish anything, make one
of them mandatory so that every client can be sure of being able
to communicate with every server. 

        - Whenever you introduce a new name space, say how it will be managed. 

        - Think of the spec as a contract, what the server promises to do
for clients. It should not tell the server how to implement, just for
any state before an operation, what the new state should be after the
operation. 

        - Each method should say which headers can be used with it. 

        - State minimum functionality that is required for compliance. 

        - Spec should include rationale for strategy used. 

        - Spec should address all requirements, and only requirements. 

I think it would be useful for all of us to add to this list, and especially
for people like Roy, Larry, and Keith, who have lots of experience working
on specifications, to give their advice.  We know we have to end up with a
document that will be clear and complete enough that people can implement to
and be confident of interoperability.  But what does a spec have to be like
for this to be so?

Here are some thoughts of mine:

1. If we decide that we want to try to stay within the HTTP framework, can
we try to model our spec on the HTTP 1.1 spec?  We could still keep the
functional divisions we have in the current spec, but within each division,
assume HTTP request and response syntax and have a section on new methods, a
section on new status codes, and a section on new headers.  Hopefully there
wouldn't be any new MIME types, but if there are, then a section on new MIME
types; and if there are any new name spaces, a section discussing them.

2. Each functional division should also talk about
        - What requirements does it address
        - What method or combination of methods can be used to satisfy each
requirement
        - Rationale for any controversial design choices

3. Add a section on why this spec is needed anyway.

4. Dependencies between sections

This is a particular weakness of the current spec. 

Make very sure that for every function we want to be able to perform, we say
what methods can be invoked to accomplish that and refer to the appropriate
section for complete syntax / semantics.  Examples are especially useful in
this situation.  And a clear and complete description of what the end state
will be.  So if the formal discussion of DELETE is in the Namespace
Manipulation section, then the Hierarchical Collections section should point
me there, but should also tell me exactly what syntax I should use to delete
a collection, with examples, and show me what the end states will be.

--Judy

Name:			Judith A. Slein
E-Mail:			slein@wrc.xerox.com
Internal Phone:  	8*222-5169
External Phone:		(716) 422-5169
Fax:			(716) 265-7133
MailStop:		128-29E

Received on Wednesday, 5 February 1997 17:18:05 UTC