[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: "Clean Specs"
At 09:19 AM 2/7/99 -0600, Paul Prescod wrote: >What is a "clean spec?" Good question, one with many answers. >People in this discussion are mixing together a variety of things that I >do not consider the same. > >Uche Ogbuji wrote: >> I have worked on teams implementing DOM, XSL and parts of XLL. Some users >> might grant that we have been "succeeding", but let me assure you that if so, >> it is despite the W3C specs, not because of them. DOM, especially is >> unforgivably inconsistent, incomplete, and unclear for a production-ready >> (1.0) specification. > >There is not a SINGLE person on this mailing list that would say that it >is right to create specifcations that are inconsistent, incomplete or >unclear. It is beyond doubt that specifications in the XML family, >including XML itself, have these problems. The question is how to avoid >that? Glad to hear that we're actually arguing toward a common purpose. > * some people say that what the spec needs is "more English". But much of >the problem with the namespaces specification comes from ambiguity in the >English. > > * some people say that we need "more non-normative text" but once again, >it is a non-normative appendix that is confusing people. > >What almost nobody has suggested is that we need more formal notation. Now >if we look at James Clark's "clarifying" document what we see is *less* >English text and *more* notation. What we need is text that conforms to the formal notation, and lots of examples that are checked hard against both the text and the formalisms for accuracy. This is extraordinarily difficult to do right, but it results in standards that are both solid and understandable. To a considerable extent this demands that spec writers see themselves as implementors - and probably that they include implementors in the process, especially implementors who don't have prior experience in whatever standards provided the foundation of the current project. The story for XML 1.0 of using Peter Murray-Rust as a canary is a good one, though I'd like to see more of that in the actual group of people writing the specs, not just the surrounding groups. One other point: putting explanatory text and examples into 'non-normative' sections is pretty much equivalent to abandoning them, announcing that the writers didn't put the effort to ensure that they were completely conformant with the formal specification and therefore equally normative. Making the _entire_ spec normative, both the formalisms and the explanatory text, seems like a more likely approach to succeed, though again it requires (considerable) additional effort on the part of the specification writers. >As David Megginson has pointed out, when a spec. invents a notation to >explain its abstract concepts the spec. becomes temporarily harder to read >because you have to learn the notation before the specification. This will >turn people off. I remember that Algebraic notation turned me off in my >first year math classes. But in the *long run* it makes life easier for >everyone. Implementors have precise definitions of what the hell they are >supposed to implement. End-users get software they can use. People reading >the specification for their own education and edification will understand >it better -- if they perservere through the task of learning the notation. Are there good resources describing formal notations? I tend to find that the people creating formal notations do so because they're fed up with text, and then do a lousy job describing the notations. All they've done is make the learning curve a hell of a lot steeper, while creating a subculture of experts fluent in that notation who then feel empowered to use that notation to create all kinds of wonderful things that the rest of us can't figure out. I would _never_ write an XML book that started by explaining EBNF and then used that to walk through the spec; I wouldn't expect readers to stick beyond the first few paragraphs. (It has been done before, and there are readers who enjoy that, but in my limited experience they're a very small minority.) >I know that W3C spec. writers are under pressure to use more normative >English and less normative notation. This is not a vote for "clean" >specifications. It is a vote for messy, hard-to-implement ones. Where is >Dan Connolly when you need him? It requires making the effort to align the text and the formalisms. Now that we have XML as a foundation, that task may become simpler; I don't find it very difficult to describe the structures of XML documents and XML DTDs in plain English, even to those without extensive XML experience. Making XML a common formal foundation is a good way out of this mess for lots of standards - though that, of course, requires undertaking the project Paul has described above of making the foundation formalism intelligible. XML won't work as a common foundation for everything, so we'll still be stuck with the other vocabularies for a lot of projects. Spec writers will still have an obligation to write clear text. >Let me point out: the CSS and HTML specifications are easy to read because >everyone who wants to read them already understands the basic concepts of >web pages and layout. They are concrete implementations of ideas we >already understand. The same goes for Java. (and yes, I read the Java >specification, but AFTER I already knew Java) CSS was actually a huge jump for a lot of people in the HTML world; I'd say it was harder than you make it out to be. CSS2 is easy to read because it recognizes that difficulty (more than CSS1 did) and addresses it directly. I've never found the HTML specs to be of much use, though the latest drafts look much more promising. >I wonder if anyone on this list has ever learned a language that was >radically different from what they already knew through the language >specification: Scheme, Prolog, APL? Never tried radically different. I found the ECMA-262 spec for ECMAScript/JavaScript much more useful for syntax than the books I was attempting to use at the time, though that too required some effort. >Technical writing is damn hard. When you do it right, you must make >certain decisions about ordering of concepts and revelations that are the >exact opposite of what you do in writing a specification. When you write a >spec., you need to present things in the order of fundamental building >blocks to high level concepts. In technical writing you will put your >students to sleep if you zoom in on details before explaining the general >framework. It's definitely difficult. I've spent about 100 hours this week documenting assorted XML material to finish a book, and I've seen specs with varying degrees of clarity, from super-sharp to non-existent. (I've also been dealing with numerous cases where text and formalism don't match at all. That's especially fun.) I'm not convinced that technical writing needs to run backward from the way that a specification must be written, however. Starting out with building blocks and constructing grander concepts is perhaps a nice theoretical model, but I don't think I've seen too many specs that follow that construct precisely. Typically, specs at least present the big picture to give readers some idea of why they're bothering, then focus in on details, and then zoom back out. Abstracts and introductions are at least as important to writing a good spec as they are to writing a book, as are glossaries. >Life is hard for implementors. I'd rather >be forced to implement the entire suite of XML specifcations over HTML/CSS >2. That isn't a slight against HTML/CSS, it's just an attempt to put >things in perspective. Actually, once they get through the HTML-in-XML stuff, I think implementing HTML/CSS2 would be a heck of a lot easier than implementing XML/XLink/XPointer/XSL/fragments/XQL/etc. That's your choice, of course. Simon St.Laurent XML: A Primer / Building XML Applications (March) Sharing Bandwidth / Cookies http://www.simonstl.com xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1 To (un)subscribe, mailto:majordomo@i... the following message; (un)subscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|