Re: [office-comment] Hard to know conformance requirements (ODF pt 1, public review 1)

[marbux <marbux@gmail.com>]

On Mon, Feb 8, 2010 at 6:54 AM, Alex Brown <alexb@griffinbrown.co.uk> wrote:
x--snip--x

> When "is" is used, it is not clear whether this is mandatory behaviour or recommended behaviour - and it is not possible to understand always whether something needs to be done or some existing state is being described.

x--snip--x

> - Make an editorial pass of the text checking for provisions made using clauses build around present tense verbs; recast them to use ISO control language ("shall", "should", etc.) as appropriate.

The culprit here is reliance on passive voice clauses whereas the
active voice is required to write a conformance clause. The result is
usually an untestable statement. See e.g., W3C Working Group Note, A
Method for Writing Testable Conformance Requirements, section 2,
<http://www.w3.org/TR/test-methodology/#common-mistakes>:

"When working on a specification, there are common mistakes an editor
can make when writing conformance requirements that makes them
difficult, if not impossible, to test. For technical specifications,
the testability of a conformance requirement is imperative:
conformance requirements eventually become the test cases that
implementations rely on to claim conformance to a specification. If no
implementation can claim conformance, or if aspects of the
specification are not testable, then the probability of a
specification becoming a ratified standard, and, more importantly,
achieving interoperability among implementations, is significantly
reduced.

"The most common mistakes that editors make when writing conformance
requirements include, but are not limited to:

...

"Using a passive voice for describing the behavior, e.g. “an invalid
XML file must be ignored” — this hides what product is supposed to
follow the prescribed behavior."

Passive voice can work for definitions; not so for testable
conformance clauses. Use of a word processor with a competent grammar
checker could significantly speed the process of converting passive
voice clauses to active voice.

Best regards,


Paul E. Merrell, J.D. (Marbux)


-- 
Universal Interoperability Council
<http:www.universal-interop-council.org>