Re: Marking up assertions in our documents

Greetings Shane, I'd suggest that 1) and 3) need to be combined leaving 
two alternatives:

1) Get someone who knows what they are doing to design new styles for our 
assertions and document the convention in the overview of each spec so 
people know what we are trying to accomplish., or

2) Remove the styles altogether since they do not currently add any value.

I have been doing some work with people in WS-I and EIC on documenting 
assertions in such a way that they are not only readable but can be 
extracted from the specification for machine processing.

Regards, Roland




Shane McCarron <shane@aptest.com> 
Sent by: public-xhtml2-request@w3.org
14/11/2007 16:26

To
XHTML WG <public-xhtml2@w3.org>
cc

Subject
Marking up assertions in our documents







Some time ago, we adopted a convention of marking up assertions so they 
could be readily identified.  When we did that, I (stupidly) introduced 
some css styles to highlight the assertions.  I purposely made these 
styles obnoxious so that someone would complain and fix them.  I also 
neglected to ever explain the convention anywhere.  Then I forgot all 
about it.

Roland has pointed out to me that our documents have obnoxious orange 
highlights in them, which he thought were diff marks.  Nope - 
assertions.  Not defined nor described anywhere.  I propose we do one of 
the following:

1) Get someone who knows what they are doing to design new styles for 
our assertions, or

2) Remove the styles altogether since they do not currently add any 
value, or

3) Document the convention in the overview of each spec so people know 
what we are trying to accomplish.

See, for example, http://www.w3.org/MarkUp/2007/ED-xhtml-access-20071030/


-- 
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: shane@aptest.com










Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU