[xhtml-role] Editorial

Hi,
This is a QA Review comment for "XHTML Role Attribute Module"
http://www.w3.org/TR/2006/WD-xhtml-role-20060725/
2006-07-25
1st WD

About http://www.w3.org/TR/2006/WD-xhtml-role-20060725/

1. Use English and direct links when possible

 "The XHTML Role Attribute defined in this specification 
 provides XML languages with the ability integrate a "role" 
 attribute into any markup language based upon [XHTMLMOD]."

For example in this paragraph, replace 

 "upon [XHTMLMOD]"
by
 "upon <cite><a href="http://www.w3.org/TR/2006/PR-xhtml-modularization-20060213">Modularization of XHTML 1.1</a></cite> [XHTMLMOD]"
 
 For the reader of the specification, it is indeed good to have references to modules in the references sections but also to have the possibility to access directly the referenced specification.
 Even more if the specification refers to a specific part of another specifications.

2. Use markup which helps to parse or extract information from the document
 For example, replace
 "role" by "<code>role</code>"
 or "<code class="xhtml">role</code>"

3. Factual information

 Remove from the prose of the specification factual information which will not make sense anymore after a few years. These bits of information if considered useful should be either in the status or maybe in an appendix.

4. Normative and examples

When you give example in normative sections make it clear that they are not part of the normativity. For example, in the document conformance section, you give an example in the paragraph which defines a requirement.

 "The namespace for XHTML Role Attribute Module is defined 
 to be http://www.w3.org/1999/xhtml. An example start tag 
 of a root element might look like:
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" >""

5. uppercase/lowercase for RFC 2119

 Verify the document like for example:
 "A conforming user agent must support all of the features 
 required in this specification."
 
6. broken anchor

 <a class="aref" href="Overview.html.html#adef__role">role</a>
 URI-reference doesn't exist, URI is wrong




-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Thursday, 10 August 2006 07:38:06 UTC