Re: [xml-dev] Schematron Question: proper way to express the textversion

[Rick Jelliffe <rjelliffe@allette.com.au>]

Costello, Roger L. wrote:
> Hi Folks,
> Within the <sch:assert> element you can provide a textual description
> of the assertion (which I indicate above using "-- text version of
> assertion --").  What is the best way of stating the text version of an
> assertion: 
>
>          "is", "should be", or "must be"?
>   
In English? Who knows!
> For the above example, which of these is best:
>
> (a) EndTime is greater than StartTime
>
> (b) EndTime should be greater than StartTime 
>
> (c) EndTime must be greater than StartTime
>
> Or perhaps something else?
>
> What is recommended?
>   
 For contingent constraints, such as business rules, I tend towards the form

   An X should be Y, because Z.

For necessary constraints, such as your date range example, I tend 
towards the form

  An X must be Y.

For example
 <assert test=" startTime &lt; endTime " role="rangeConstraint">
  Meeting times are specified by two times. The start time must be 
earlier than the end time.
 </assert>

You might consider specifying the assertion text in terms of the problem 
domain rather than the markup. This way the assertion can be written or 
maintained by domain experts who don't know the particular serialization 
used, and the assertion can be understood by users who have the XML data 
mediated through some GUI (and so cannot see the element names or 
structures.)

One approach is to think "Are these assertions compehensible if typeset 
as bullet points?"  (I think Michael is correct to bring up the expected 
users of the text, though they may not be used as validation messages or 
diagnostics as  Roger mentioned.) In fact, you might even think "What 
forms of assertion allow maximum repurposing?"

Even for texts that are not diagnostic, the tone may be important. An 
old usability text I read said that users react strongly to messages 
that they think are strident and which seem to blame the user. So 
shifting "must" to the more polite "should", which will be a locale- and 
language-dependent consideration of course, might be friendly. On the 
other hand, when assertions are used contractually, then precision and 
definiteness may override politeness, I suppose.

Cheers
Rick Jelliffe