Guidelines for Open A11y Specifications

• 1 Guidelines for Open A11y Specifications
  • 1.1 General Boilerplate Materials
  • 1.2 MarkUp Guide for Open A11y Specifications
  • 1.3 Syntaxic Conventions for Open A11y Specifications

• The feedback address for all Open A11y specifications will be accessibility-rfc@a11y.org
  • The feedback address will be included in each specification's Introduction (after verbiage such as “this specification was developed by the LF/Open A11y Workgroup. To provide feedback, report errors or inquiries, please send email to accessibility-rfc@a11y.org” and in the ADDRESS section of the specification.

• The document-type of Open A11y specifications will be XHTML 1.0 Strict
  • all tables used in a specification must contain (at least): a summary, headers/id bindings, scope and a CAPTION; styling of tables should be handled with CSS, rather than be hard-coded into the TABLE

• Expansions must be provided for all acronyms and abbreviations; after the initial expansion, the first use of an abbreviation and/or an acronym must be provided with an expansion.

• All Open A11y specifications 'must' contain an ADDRESS element, containing: contact information, means of providing feedback, reporting errors, etc.. The ADDRESS will also contain boilerplate Open A11y/Linux Foundation verbiage as far as copyright and permissions are concerned, as is common at the bottom of technical specs

• All Open A11y specifications need a normative references section. For example, to document RFC2119 in the text, the string RFC2119 should point to an entry in the Normative References section. This will assist in the stability, longevity and maintenance of the document, as the links contained in the text will not be broken when a resource moves or a URI changes, but can document when the resource was accessed and make it easier to universally effect a change to a single URI through an accompanying errata document. (a note on the example: this is supposed to be an example of code contained in a DL, but since the wiki allows certain HTML/XHTML markup without using HTML containers normally used to insert straight markup into a wiki page, and i have yet to be able to get the markup example to be rendered correctly)

  * **[RFC2119]</dt>**
  * //<a href="[[http://www.rfc-editor.org/rfc/rfc2119.txt|http://www.rfc-editor.org/rfc/rfc2119.txt]]"
   >Key words for use in RFCs to indicate requirement levels</a>//,[[http://www.ietf.org/rfc/rfc2119.txt|RFC 2119]], S. Bradner, March 1997.\\ 
   Available at: [[http://www.rfc-editor.org/rfc/rfc2119.txt|http://www.rfc-editor.org/rfc/rfc2119.txt]]</dd>

• a unified “look-and-feel” (as well as sounds for aural styling, which can be added later without affecting the spec) needs to be established

• it is strongly recommended that CSS be used for controlling the printed version of the spec when a user prints the XHTML document

• Dublin Core markup will be used in the HEAD of Open A11y specifications, using the meta element;

  <meta name="DC.Title" content="" />
  <meta name="DC.Title.Alternative" content="" />
  <meta name="DC.Creator.PersonalName" content="Author Name1" />
  <meta name="DC.Creator.PersonalName" content="Author Name2" />
  <meta name="DC.Subject" content="" />
  <meta name="DC.Description" content="Description of specification;
  probably excerpted from the Abstract or Introduction" />
  <meta name="DC.Publisher" 
  content="Open Accessibility (A11y) Workgroup of the Linux Foundation" />
  <meta name="DC.Rights" content="" />
  <meta name="DC.Type" content="Text" />
  <meta name="DC.Format" content="text/html" />
  <meta name="DC.Identifier" 
  content="URI of Specification" />
  <meta name="DC.Language" content="us-en" />

• All Open A11y specifications will conforms to RFC2119 to specify declarative, normative keywords, for example:
  
  • “The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].”

• All anchor values must be lower-case

• Any anchor name/id must be human-parseable
  • when a term is defined, the anchor to that definition should take the form def-foo, where foo is the concept's name; for example, def-mousekeys

• Open Accessibility Workgroup's main page
• Open Accessibility's Draft Specification Index
• Open Accessibility's Specification Issues and Questions