- From: Judith Slein <slein@wrc.xerox.com>
- Date: Wed, 5 Feb 1997 14:19:54 PST
- To: w3c-dist-auth@w3.org
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