W3C home > Mailing lists > Public > www-html-editor@w3.org > July to September 2006

[xhtml-role] Editorial

From: <karl@w3.org>
Date: Thu, 10 Aug 2006 07:37:43 -0000
To: www-html-editor@w3.org
Message-Id: <20060810073802.EEC0C4F35B@homer.w3.org>

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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 27 March 2012 18:17:55 GMT