- From: Edward L. Knoll <ed.knoll@cosd.fedex.com>
- Date: Mon, 23 Sep 2002 08:53:06 -0400 (EDT)
- To: "Kay, Michael" <Michael.Kay@softwareag.com>
- CC: Jeni Tennison <jeni@jenitennison.com>, public-qt-comments@w3.org, Mike Brown <mike@skew.org>
> > What can the WGs do to stop us from walking away? I don't > > know, but shorter and better-organized specs would be a > > start. They should consider separating the implementation > > details from what a user needs to know. > > > > I mean as an implementer, I can appreciate things like > > spelling out what conditions create what type of errors, and > > very detailed, accurate, verbose explanations with very > > specific terminology to describe the minutia. > > > > But take, for example, the section on format-number(). As a > > user just trying to remember the format of the arguments so I > > can format a number in my stylesheet, I pore over the 3000 > > words(!) in that section only to come away > > *still* scratching my head as to how the heck to use the > > stupid function. > > W3C specifications have never aimed at being a tutorial for users. The XSLT > 1.0 specification of format-number() was a disaster: it didn't have enough > detail for either implementors or users to predict the effects of a given > call, without trying it out against a JDK 1.1 implementation to see what > happened. The new specification is not ideal - it describes an algorithm, > which is something we usually try hard to avoid - but at least it tells you > what the function does for any given input. > > > > Another example, just a minor nit: explaining push vs pull > > processing. That's all good for people to know, but it's a > > design pattern, not something that needs to be wasting space > > in the spec. "Why did I just read that" or "why is > > that being explained here, in between that and this" should > > not be questions I am tempted to ask. > > We've had some difficulty getting the right level of introductory material, > and organizing it to make it accessible. I certainly wouldn't claim that > we've got it right yet. But there are two pressures: to explain things more > clearly, and to stick to the normative facts. It's not easy to find the > right balance. > > > > Scroll down a little bit and the sheer volume of terminology > > being introduced is overwhelming. How is someone supposed to > > read this and "get" it? XPath 1.0 wasn't arranged all that > > well, but at least it was concise and requires little more > > beyond the spec itself than a few more examples and diagrams > > before someone can understand it -- "Here's your data types, > > here's your tree model, here's your syntax and semantics, > > here's your function library." > > Well, there were things in XPath 1.0 that people had immense difficulty > with, for example the notion of axis direction and "proximity order". I > actually think the main XPath 2.0 language book is a vast improvement, both > in terms of specifying the language accurately and precisely, and in terms > of readability. I do agree that we have a problem of duplication and > consistency across multiple specifications - this is largely a consequence > of our internal processes, where we have tried to subdivide the task among > different subgroups and editorial teams. I think we should perhaps review > whether some reorganisation of the documents is possible now that the > technical content has become reasonably stable. Any concrete suggestions > along these lines would be welcome. > > > > These new specs are going to require *volumes* of > > supplementary material written in the Common Tongue to get > > even experienced XPath/XSLT 1.0 users up to speed with it. On > > the other hand, I suppose it gives writers of articles and > > books on these subjects something to do. SGML, anyone? > > > You seem to be expressing two separate concerns > > (a) that the language is too big, and > (b) that the document set is unwieldy I haven't reviewed the document, so am only commenting on the post, but why are you constrained to a single document? You say it difficult to maintain a balance between introductory material and normative facts; I'd say it's impossible. An (useful) introductory text tends to stick to the fundamentals and core, most often/likely used features. A good reference has to describe all features/aspects. Mixing them (as rule) tends to mean we lose the signal for the noise on both sides of the fence: the person who wishes the introduction is overwhelmed by the mass of material, the person attempting to research a specific point/feature is frustrated at all the excess material they have to go through. Any reason why you're constrained to a single document (outside the minor issues of additional work load, overhead of generating a second document, and trying to set a new precedent)? Regards, Ed Knoll -- Edward L. Knoll Phone (work) : (719)484-2717 e-mail (work) : ed.knoll@cosd.fedex.com e-mail (business): eknoll@sf-inc.com e-mail (personal): edward@elknoll.com
Received on Tuesday, 24 September 2002 03:24:29 UTC