Editorial Style Guide

Please follow these style guidelines for PF documents. Use the following resources in order of priority:

1. W3C Manual of Style
2. Chicago Manual of Style
3. This style guide

Document style

• There should always be introductory content before starting subsections.
• Sequences of steps use ordered lists, the first paragraph of which labels the step and is in a <strong>; subsequent block elements are the content for the step.
• Preformatted examples should "pretty-print" the example to be less than 80 characters wide, and indent the code using 2 space characters per indent step. Wrap within an element tag with an extra indent. Use line break characters, not <br/> elements, for new lines. Add extra line spacing as useful. They use the class "example". Use the Code Sample Expander tool to assist with this.
• Keyboard characters should be in kbd elements.
  • Spell out keys such as "control", "shift", "command", "option", "alt", "insert", "pageup", "enter", etc.
  • Use plus as delimiter for keys that are pressed together, e.g., control+v
  • Use comma as delimiter for keys that are pressed in sequence, e.g., insert, m
• Language elements should be in code elements.
• The first reference in a section to a role or state should be linked to the role or state with the appropriate class. Subsequent references needn't be referenced, but may be in certain circumstances.
• repeated links to aria features should just be in <code>, not in cross-reference links (just link first time)
• Headings use title case.
• "step" headings, the bold sentence at the start of a numbered list item in a list of steps, are sentence case and not marked as an actual hx element. They should summarize what the following paragraphs get into.
• Subheadings: only use sub-headers (<h{x+1}> following <hx>) if there are at least two of them. If there isn't more than two sub-sections, it isn't a sub-section and should be integrated into the parent section.
• Lists: only use lists of two or more items. If it's only one item, it isn't a list and should have a different semantic.
• Terms like "Web" are capitalized when it's "the Web", but not when referring to "web applications". Same for "internet, rich internet applications".
• Synopsize the meaning of abbreviations and glossary terms the first time they are used in a section.
• Acronyms we don't expand (but wrap in <abbr> elements):
  • API
• Acronyms we do expand (don't use the acronym)
  • RIA (use rich internet application)
  • AT (use assistive technology)
• Cross reference links don't include section numbers.
• Refer to states and properties in prose as "attributes", not as "states" or "properties" in order to be less confusing. (though they're still formally states or properties)
• @@Shawn's referencing conventions

Preferred terminology

• When referring to an instance of a role, use "element with a role of X", not "X role" or "X element". "X role" refers to role in the taxonomy itself; "X element" is not technically meaningful.
• "Ajax" is not spelled "AJAX"
• "Assistive technologies" is plural, not singular.
• Use "WAI-ARIA" instead of "ARIA", to avoid trademark confusion.
• Use "text alternative" instead of "text equivalent" or the like, for consistency with WCAG 2.0 usage.
• Reference "DOMClick" instead of "DOMActivate" which is going to be deprecated or made optional.

Specification rules

• Descendants of the composite role MUST NOT have the "nameFrom" value of "contents" set.
• The composite role and its descendants MUST NOT have a childrenArePresentational value of "true".

CSS classes used for visual styling

ednote

Editorial notes are marked with "ednote". Editorial notes differ from todos in that they are notes to the public, usually about an unfinished piece, and are not removed from the draft when going to TR. However, the document should be clear of editorial notes from the Last Call stage onward. This is typically used on a <p> element, or on a <div> if it encompasses multiple block elements.

note

A general note for clarification is marked with this. This is part of ordinary document structure. This is typically used on a <p> element, or on a <div> if it encompasses multiple block elements.

example

A code example should be marked with this. This typically goes on a <pre> or <div> element.

termref

Links to definitions of terms use this class, for visual styling.

img

This is used for visual styling of an image. The class can be used on an <img> element directly, or on a <div> wrapped around the image. If used on a <div>, a <p> inside the <div> in addition to the <img> should be used for a caption.

role-screenshot

Screenshots of widgets exemplifying a particular role use this class for visual styling