[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Standards and their users
Miloslav Nic wrote about standards - > Recently I have received quite a few mails complaining about standard > understanding and have > seen quite a few more on different mailing lists. > > I recommend these two to your attention: > > http://lists.zvon.org/l/showmsg.xp?ln=zvon&mid=18 > http://lists.zvon.org/l/showmsg.xp?ln=zvon&mid=7 > > I am afraid that the gap between standards creators and their user > community is widening with startling pace. From the time I have started > Zvon I have spent hundreds of hours studying standards and in my > personal experience it gets more and more difficult to read the next > one. > I completely agree that the current standards are difficult to read and understand, and would them to be more intelligible. There are actually two separate aspects to this: 1) Whether to illustrate requirements with examples or not. There are different approaches to this. Some think that examples must be forbidden, some that they should be liberally used. 2) The writing quality - clarity vs. formality. Sometimes formality is confused with comlexity, and simplicity in the text with lack of clarity. Why would examples be forbidden? Mainly because the text should stand on its own (i.e., be "normative" - a terrible word, I think!). Also, examples might be inconsistent with the text, and then which should be followed? Why should examples be allowed? Because no text can stand completely on its own, especially if the readers don't understand all the private concepts and expressions that could not be completely spelled out. Look at the legal profession. Nothing else is as precise and complex as a legal document or law, but court decisions are still required to interpret the intended meaning. The W3C recs are all over the place in terms of these two aspects. I mean no disrespect to the editors, who (I am very sure) work very hard and probably have an impossible job. The language in any one document ranges from extremely concise and precise to sentences that seem to have been added because someone thought they read well. Diagrams, when they are used, are sometimes not as helpful as they could be. Generally, I would say that the language - especially sentence structure - is much too complex. It would be better to pay more attention to what needs to be conveyed to the rader, and to split up the language into simpler parts with this in mind. However ... If you look at other specs, not necessarily software-related ones, it's the same thing. Try reading up on ASTM tensile testing methods, or the requirements for nuclear-reactor-qualified stainless steel pipes, or standard threaded bolts. You have to learn how to read them - it is an art that takes experience. Writing them is even harder. One gets to really appreciate a concise and precise statement of a requirement. Standards are a form of infrastructure. They need to be understandable by those who build the tools and systems - parsers, protocols, and so forth. Those builders must be able to go back to the standards, in case of questions, and verify what is meant. Others skilled in the art should be able to reach the same conclusions, or at least they should all be able to reach a "gentlemen's agreement" about how to interpret the language. This is how it works in C and Java, after all. Tried reading up on the standard C library? Ha! This should be the test for a standard. Judging from the type of questions that get raised here, the XML recs are marginal in this regard. Still, the parser, xslt processor, and schema engine people seem to be able to build their processors, so the Recs must be more or less adequate. What about the rest of us? That's where good texts and products that come with lots of useful examples come in. Michael Kay's xslt book is a really good example. Personally, I like the approach of including a tutorial with the rec, as the xsl-schema rec has tried to do with the part 0:Primer. Too bad these books and tutorials can't exist at the beginning. But then, it's too bad most programmers don't comment their code adequately, too. The reasons are probably similar. So let's encourage - even demand - the standard writers to improve their writing (this means to be specific when we give comments and make requests during development), and let's applaud people like Michael Kay and Miloslav Nic who work hard to give the rest of us material we can work with. Whew-that-was-long-windedly-yours, Tom Passin
|
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
|