======  Guidelines for Open A11y Specifications ======
=====Contents=====

  * [[https://www.linuxfoundation.org/#Guidelines_for_Open_A11y_Specifications|1 Guidelines for Open A11y Specifications]]
    * [[https://www.linuxfoundation.org/#General_Boilerplate_Materials|1.1 General Boilerplate Materials]]
    * [[https://www.linuxfoundation.org/#MarkUp_Guide_for_Open_A11y_Specifications|1.2 MarkUp Guide for Open A11y Specifications]]
    * [[https://www.linuxfoundation.org/#Syntaxic_Conventions_for_Open_A11y_Specifications|1.3 Syntaxic Conventions for Open A11y Specifications]]


\\ 
===== General Boilerplate Materials=====

  *  The feedback address for **all** Open A11y specifications will be [[https://lists.linux-foundation.org/mailman/listinfo/accessibility-rfc|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 [[https://lists.linux-foundation.org/mailman/listinfo/accessibility-rfc|accessibility-rfc@a11y.org]]" **and** in the ''ADDRESS'' section of the specification.

\\ 

----
===== MarkUp Guide for Open A11y Specifications=====

  *  The document-type of Open A11y specifications will be [[http://www.w3.org/TR/xhtml10/|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)
<code>
  * **[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>
</code>

  *  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;
<code>  <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" /></code>

\\ 

----
===== Syntaxic Conventions for Open A11y Specifications=====

  *  All Open A11y specifications will conforms to [[http://www.rfc-editor.org/rfc/rfc2119.txt|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''

\\ \\ 

----

  *  [[:accessibility:start|Open Accessibility Workgroup's main page]]
  *  [[:accessibility:specs:start|Open Accessibility's Draft Specification Index]]
  *  [[:accessibility:specs:guidelines:issues|Open Accessibility's Specification Issues and Questions]]