Cart
|
[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Improved writing -- who's going to pay for it?
 Ronald Bourret wrote: > > tpassin@h... wrote: > > > > Yes, I know, but better writing/editing makes the result stronger and > > (potentially, at least) more useful to those same companies. > > I'd remove the "potentially". The result is always more useful. > > The schema spec is a good example. Once I finally waded through it, I > found I liked most of what it offerred. Contrast that with the fact that > even now, whenever I pick it up, I get really p----d off at the fact I > can't understand anything it says. I can't help but wonder how much of > the controversy over schemas was due simply to frustration. All spec-writers face the same kind of problem. If one uses algebras then no-one can understand it. If one uses simple formalisms then you end up having to add so many exceptions in text that the simple formalism is misleading. If you define a technical vocabulary and use simplified English, then people insist on reading it as if it were natural English and with the words meaning whatever they mean in the domains that the reader is familiar with. If you use natural English, then it is too fuzzy to communicate, and the idioms and vocabularies of one nation are not shared by others (for example, someone complained that the XML Schema spec used "elide" and "obtain" in ways that seem perfectly usual to me.) The prime readers of XML Schemas specification is implementers of XML Schema processors; a secondary audience is developers of XML Schemas (hence the Primer). Intelligability in one sitting is simply not a major goal, though it would be lovely. After anything gets to a certain level of complexity, a linear exposition is not possible and so a symphonic exposition is required: it is a perhaps version of the writers' classic dilema of how to handle recursive definitions (e.g. how to introduce entity references in an exposition on XML data content before you have introduced markup declarations). There are a dozen ways to organize the Schema specs for clearer exposition for users, and I hope authors will soon be busy on finding them out. The most telling issue is this: people who have written specs very rarely complain about the prose of other specs. Instead, they often have great sympathy for the view that you should either limit the technology to ways that can simply explained (i.e. sacrifice power for expositional simplicity, but then people will complain about lack of bangs per buck) or you should pick the most elegant algabra for explaining it even if then you need to spend a lot of effor explaining what it means (i.e. the e=mc^2 effect). I am not saying "put up or shut up"; but there is something practical you can do: when you find a paragraph that is bad, draft an improvement and send it to the xml schema comments mailing list. It won't make it in time for the CR draft now, but I am sure the editors will be delighted to have suggestions. The editors are not trying to create incomprehensible specs: to the contrary they are trying very hard to integrate the progressive refinements of XML Schemas by the XML Schema Working Group. Cheers Rick Jelliffe 
|
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
|
|||||||||
