mode of examples [imperative?] and plain-ish English vs. spec-ese

At 02:02 PM 2000-04-24 -0400, Ian Jacobs wrote:
>Cynthia Shelly wrote:
>> 
>> Hi All,
>> 
>> It's not entirely clear when reading the guidelines that the examples are
>> non-normative.
>
>Cynthia,
>
>Section 3 says that for each checkpoint there are:
>
>  "Optional informative notes, clarifying examples, 
>   and cross references to related guidelines or checkpoints. "
>
>The "informative" is supposed to distribute to the whole sentence.
>

Yeah, but out here amung us good ol' boys, it don't.  So this sentence
doesn't get the point across for an important segment of our intended
audience.

Usage:  'optional' is what you tell the guidelines author, not the
guidelines reader, about the material that may or may not be there in the
document in addition to the core guideline.  It is confusing here.  Better
to use 'may' in describing the on-again, off-again presence of the
elaborations.  The term 'optional' in the guidelines should be reserved to
substructures or propositions which may or may not be present or true at
the _content provider's option_.

Besides, the cross references are a mixed bag of normative and
non-normative references.  So if the 'informative' is supposed to be
interpreted with an ISO geek hat on, then the quote as presently stated is
broken.

'illustrative' examples is the best plain English I know for what is
intended here.  That is, best on a balanced evaluation both for actually
meaning what is intended and meaning that to the broadest readership.

Al


> - Ian
>
>-- 
>Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
>Tel:                         +1 831 457-2842
>Cell:                        +1 917 450-8783
>

Received on Monday, 24 April 2000 15:06:23 UTC