SBVR16 — Use of SBVR markup in specifications

Specification: SBVR v1.3

Summary:

Experience with DTV teaches that the SBVR markup practices are very expensive in editor time, and do not improve readability of definitions and necessities in OMG specifications. The marked up text can only usefully be output from an authoring tool; the author should be able to input plain text for definitions and necessities. And, in the case of complex definitions, the markup reduces the readability of the text.

The function of the markup as output from a tool is twofold:

• to allow the business analyst to identify vocabulary entries in text

• to allow the business analyst to verify that a text consists only of keywords and vocabulary entries

In the absence of a tool that can recognize vocabulary and keywords in plain text and generate the marked up form, it should not be the practice of OMG specifications to use the markup. Further, even when it is possible, the use of the markup in definitions and necessities reduces readability, partly as a consequence of oversize sans-serif font, which is known to disrupt the visual flow of text to readers. In short, SBVR itself “leads by bad example” in this area.

SBVR should be clear that its use of markup is what one might expect a tool to be able to do, but not what one would expect an author to provide. And it should be made clear that the use of SBVR has nothing to do with using the markup, while the vocabulary headings are important. (The best example would have been not to use it in the SBVR spec.)