Re: [xml-dev] Quote of the day

[Roger L Costello <costello@mitre.org>]

Good comment from a colleague:

If I've learned one thing as a systems engineer, it's that documenting the *rationale* for requirements provides key context above and beyond even "perfectly" formulated language in a specification.

When the original specification authors are long gone, well-formed specification language plus good rationale on why the requirement exists allows for consistent understanding and implementation and just as importantly the context to ensure that modifications to a specification don't lose the original point of the requirements.  Including some of the not-so-obvious thinking on underlying trade-space such as accounting for resource constraints at the time and "unintended consequences" that were deliberately avoided.

-----Original Message-----
From: Michael Kay <mike@saxonica.com> 
Sent: Thursday, May 12, 2022 12:27 PM
To: Roger L Costello <costello@mitre.org>
Cc: xml-dev@lists.xml.org
Subject: xml-dev] Quote of the day

My take on this is that the job of a spec is to communicate, very clearly and precisely. Some formalisms help communication, clarity, or precision, and some don't. Some achieve precision at the cost of clarity. It's the job of the spec author to find a way of ensuring that spec readers can discover the intent as easily as possible and with no risk of misunderstanding.

I've seen too many specs where formalism gets in the way. An example was the XQuery Formal Semantics. A consequence of using formalisms in that spec was that very few people were capable of reading it and finding the errors; there's no point in adopting a formalism if it has the effect that errors go undetected because no-one reads it. In most cases where I've seen people try to produce formal specs, it becomes so inaccessible that someone else tries to write a non-normative exposition, and that's what the implementors end up using, which completely defeats the purpose.

On the other hand there are plenty of specs where formalism is desperately lacking. XSLT 1.0 and XPath 1.0 are examples; the RFCs for URIs are another. The specification of xsl:number in 1.0, for example, is hopelessly vague; this led to lots of different interpretations by implementors. We put a lot of effort into improving this for 2.0.

XSD has some good ideas in terms of techniques for communicating precisely. The main problem is that these techniques aren't clearly explained. Section 1.3, explaining "documentation conventions and terminology", is far too short, and presumes far too much understanding. Take the sentence: "The correspondence between an element information item which is part of the XML representation of a schema and one or more schema components is presented in a tableau which illustrates the element information item(s) involved." That sentence is hard to parse and it contains many words and phrases that the reader is likely to struggle with. The word "tableau" is pseudo-formal - it's an unusual word so you think it must have a technical meaning, but it doesn't. The term "element information item" is defined in other specs, but there is no hyperlink to the definition. The term "schema component" is a forwards reference to a concept described, but not well explained, in section 3, and again, there is no hyperlink. So the reader is wading through mud. When you've read the spec three times, very carefully, you start to be able to read sentences like this and realise what they mean, but until then, you're all at sea. And if you can't understand the section that explains the documentation conventions, what hope is left?

Michael Kay
Saxonica

> On 12 May 2022, at 15:48, Roger L Costello <costello@mitre.org> wrote:
> 
> Lessons that I learned from Michael's quote:
> 
> 	When writing a specification, not all things
> 	need to be specified formally. Don't have
> 	spurious formality. However, there are some 
> 	things that need to be specified very rigorously; 
> 	for them, do specify them formally.
> 
> /Roger
> 
> -----Original Message-----
> From: Roger L Costello <costello@mitre.org> 
> Sent: Thursday, May 12, 2022 6:54 AM
> To: xml-dev@lists.xml.org
> Subject: Quote of the day
> 
> "Yes, working with the XSD specification is a nightmare; it's the toughest spec I've ever had to work with other than Algol 68, and unlike Algol 68, some of the apparent formality turns out to be spurious; when it gets to tricky things that ought to be formal, like whether two types are identical, the spec bails out."
> 
> -- Michael Kay
> 
> _______________________________________________________________________
> 
> XML-DEV is a publicly archived, unmoderated list hosted by OASIS
> to support XML implementation and development. To minimize
> spam in the archives, you must subscribe before posting.
> 
> [Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
> Or unsubscribe: xml-dev-unsubscribe@lists.xml.org
> subscribe: xml-dev-subscribe@lists.xml.org
> List archive: http://lists.xml.org/archives/xml-dev/
> List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
> 


_______________________________________________________________________

XML-DEV is a publicly archived, unmoderated list hosted by OASIS
to support XML implementation and development. To minimize
spam in the archives, you must subscribe before posting.

[Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
Or unsubscribe: xml-dev-unsubscribe@lists.xml.org
subscribe: xml-dev-subscribe@lists.xml.org
List archive: http://lists.xml.org/archives/xml-dev/
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php