EWG:Writing Directions
From TEITAC
TEITAC Wiki > EWG > Writing Directions
Directions for Writing Provisions for TEITAC Subcommittees
TEITAC Editorial Working Group
Last Update: 8 May 2007
This document provides directions for TEITAC subcommittees writing provisions for the final recommendations to the Access Board.
It includes two options for how the individual provisions will be presented, for discussion and selection by the full committee.
It does not address the structure or organization of the provisions. This issue will be discussed separately, and decided on by the entire committee. The writing guidelines in this document are useful in writing clear and understandable requirements that can be used in any organization of the material.
We have used the following terminology in this document:
- Recommendations or Report – the complete final document that TEITAC will deliver to the Access Board, including any preamble, background information or other discussion.
- Standard (or Regulation) – the collection of individual provisions.
- Provision (or Requirement) – the individual “elements” of the standard.
This document includes:
- Proposed format for the individual provisions
- How to write provisions so they are easy to understand
- Examples of provisions using the format
- Lists of entries for the related information fields
Proposed format for the individual provisions
We have two proposed formats for the individual provisions:
Option 1 – Present the recommended text of the provisions in one section, with all associated discussion in a separate section. This is the approach used in the EITAAC report.
Option 2 – Present all information about each provision, together, with discussion and related information near the text of the recommended text of the provision. This is the approach used in the VVSG (Voluntary Voting Systems Guidelines). In that document, the additional information and short discussions are part of the final regulation.
Format for Option 2
This template includes both the text of the provision and additional informational fields that help define the scope or applicability of the provision. It also includes an optional discussion section for any information that will help readers understand the requirement.
Provision Title The text of the provision.
Applies to Product Types: { Choose from list } Characteristics: { Choose from list } User Activities: { Choose from list } Disabilities: { Choose from list } Discussion
Any discussion of the provision, including a brief explanation of the benefits, related “best practices,” or the rationale for making changes to existing text. If this discussion is long, it can be introduced here and then continued in an annex.
Source: { Enter § 1194 reference or 255 reference or New } Impact: { Enter economic impact / benefits } Testability { Enter how requirement can be evaluated }
Descriptions of the elements of the format
There are ten elements for each provision. They are grouped in three sections.
Title and text of the provision
These two elements are the core regulatory material. They will be written in a consistent format, following the guidelines below.
- Provision title – a short version of the provision
- Text of the provision – the regulatory text of the requirement
Applicability information
These four elements describing the scope of the provision. They use a consistent set of terminology, to help people identify which provisions are relevant to their needs (as a vendor, agency, advocate or individual). These data fields provide a list of items which is representative, but may not be exhaustive. (A list of terms to be used is in a separate section of this document.)
- Product types – classes or types of products affected by the provision
- Characteristics – elements or aspects of a product affected by the provision
- User Activities – user goals, activities or functions that the products support
- Disabilities – disabilities for which the provision is relevant
Discussion and related information
The discussion element is used to provide additional information to the Access Board to assist in the review of this material. The other elements in this group provide information about the impact and “testability” of the provisions.
- Discussion – (optional) additional information about the purpose, scope, or rationale for the provision, or to document information covered in committee discussions
- Source – the current paragraph number in either 508 or 255, or that this is a new provision
- Impact – the economic impact assessment by the committee
- Testability – (optional) any information about how a product might be tested for whether it meets the requirement. This can be a brief discussion or a reference to a more comprehensive document, which can either be an annex to the recommendations or a citation of another standard or regulation.
How to write provisions so they are easy to understand
One of the themes for this committee is the “usability of the standards.” Many different people have to read the standard and understand what they must do. This section of the document provides some guidelines for clear writing.
There is additional information and resources about clear writing and plain language on the TEITAC Wiki. We will create some “before and after” examples using these guidelines and post them as well.
Follow these guidelines to write provisions that are easy to understand. They are based on guidance from federal agencies for writing in what is known as “plain language” drawn from experience with writing legal and regulatory documents.
- Make information easy to find with clear headings.
- Talk to your readers. Use “you” and the imperative.
- Keep your sentences and paragraphs short.
- Set the context first. Put the pieces of a sentence in logical order for your readers.
- Write in the active voice (most of the time). Use the present tense.
- Put the action in the verb, not in the nouns.
- Use your readers’ words.
- Avoid gender-specific writing.
- Use bulleted lists for options (break up paragraphs).
- Use “must” (not shall) for provisions. Use “may” or “should” for guidelines.
How to write provision titles (clear headings)
Provision titles are short sentences that summarize the requirements of the provision in an easy-to-scan format.
- Write them as short statement of the topic of the provision.
- Keep them short.
- Include any information about context, where possible.
Examples:
{ We need more examples here – to come. }
How to write the provision text
{ To come. This will have examples of well-written provisions }
Examples of provisions using the format
This section has examples of how you can use the Option 2 format for provisions of different complexity.
- A simple provision
- A provision with list of detailed requirements
- A provision with alternatives.
A simple provision
This is an example of a simple provision with two discussion points.
Provide documentation of accessibility and compatibility features
You must provide users with a description of the accessibility and compatibility features of the product, including how to install and activate them. You must provide this information in alternate formats or alternate methods upon request.
Product Types: All products Characteristics: User Documentation (any type – electronic or print) User Activities: Training/learning Disabilities: All disabilities Discussion:
If you want a supplier to provide the documentation of accessibility and compatibility features, or any alternate formats, you must include this in the contract.
When the product documentation is posted online, place any links to any alternative formats in close proximity to the original content. This helps users select the most appropriate format.
Source: Subpart D. § 1194.41(a) Impact: No change in impact Testability: This provision is tested by reviewing the documentation and the formats in which it is available.
A provision with a list of detailed provisions
This is an example of a provision with a list of closely related requirements, which must all be met. They can be included in one provision, as a bulleted (numbered) list.
Provide documentation of keyboard shortcuts
You must include information about keyboard shortcuts in the documentation.
- All shortcuts for keyboard operation must be listed in one place, for easy reference.
- When the documentation or instruction lists specific mouse based actions, you must also list the keyboard commands.
Product Types: All products Characteristics: User Documentation (any type – electronic or print) Activities: Training/learning Disabilities: All disabilities Discussion:
The purpose of this provision is to ensure that anyone using the keyboard as a primary device has a complete set of information. It also ensures that when reading instructions they do not have to look in a separate reference table for keyboard information.
Source: New Impact: Impact depends on current practice Testability: This provision is tested by reviewing the documentation and the formats in which it is available.
A provision with alternatives
This is an example of a provision with alternative ways the requirement can be met (“sufficient techniques”).
Meet this requirement
This is an example of how a provision can be met in more than one way. The text of the first provision describes the high level goals and the result it will achieve. The text must clearly state that there are more than one way to meet the requirement, and whether these alternatives are at the option of the product design or agency implementation, or whether they apply to different product types, characteristics or disabilities. The alternatives may be summarized in a list in the top-level provision.
- One alternative
- Another alternative
Product Types: All products Characteristics: All characteristics Activities: All activities Disabilities: All disabilities Discussion:
The discussion can add any explanation that will help readers understand the choices.
Source: Source Impact: Impact assessment Testability: How a product can be tested against this provision One alternative
You must include any conditions that affect the choice in the text of an alternative. For example, if an alternative must be used under certain conditions, this should be stated at the beginning of the text.
Product Types: All products Characteristics: All characteristics Activities: All activities Disabilities: All disabilities Discussion
The discussion is used as it would be in any provision
Source: Source Impact: Impact assessment Testability: How a product can be tested against this requirement Another alternative
You must include any conditions that affect the choice in the text of an alternative. For example, if an alternative must be used under certain conditions, this should be stated at the beginning of the text.
Product Types: All products Characteristics: All characteristics Activities: All activities Disabilities: All disabilities Discussion
The discussion is used as it would be in any provision
Source: || Source
Impact: Impact assessment Testability: How a product can be tested against this requirement
Lists of entries for the related information fields
There are four types of information that help define the scope or applicability for each provision.
- Product types
- Product characteristics
- User activities
- Disabilities
Use terms from these lists to fill in this information for each of your provisions. This will help us ensure that terminology is used consistently in the final report.
You may find that there are terms missing, or that you need to be more specific to be accurate about the scope of a provision. If so, please add the terms you choose, and make a note of them, so we can add them to the master lists and ensure that we are all using the same terminology.
Product Types
These terms describe the types of products that might be subject to the standard.
- All product types
- Hardware
- Telephone (desktop, wireless, cordless, etc.)
- Telephone system (PBX, etc.)
- IVR (Voicemail, Autoattendant, Audiotext)
- AudioVisual equipment (Video Monitor, TV, Projector)
- Public information terminal (Kiosk)
- Network interface to devices
- Desktop computer system
- Portable computer system (laptop, PDA, tablet)
- Copier, printer, scanner, other similar peripheral
- Software (installed or through browser)
- Web content
- Media content (audio/video)
Product characteristics
These terms describe characteristics, components or features of products
- Physical controls or connectors (latches, slots, etc.)
- Touchscreen or touch sensitive buttons (non-mechanical)
- Context-driven control (softkeys)
- Mouse/Pointer Input
- Keyboard (physical)
- Printed text, labels, etc on the product itself
- Visual display with text
- Visual display with graphics
- Color (on keys, labels, displays, indicators, documentation, etc.)
- Sound output – speech
- Sound output (other than speech)
- Speaker held to ear or product projects large magnetic field
- Speech encoding and transmission
- Speech recognition
- Biometric identification feature
- Time synchronized media
- Time limits of any type (timeout, double-clicks, keyrepeat, session length)
- User documentation (any type – electronic or print)
- Customer support/training
- Supports user-installable at
- Does not allow user-installable at (closed by policy)
- User-installable at not feasible (underlying technology limit)
- Could support user-installable at, but no at available
- Passes information/data through (e.g. transmits or transports)
- Electronic forms (web & other electronic)
- Web content or applications
- Allows user preferences
- Network-based service or feature
- Connects to a network for a service or feature
User activities
These terms describe the user goals, activities or functions that the products support.
- Conversation (voice, text, video)
- Data analysis (spreadsheet, database)
- Document creation and editing (text, graphics, layout)
- Document sharing and reviewing
- Media (audio/video) creation and editing
- Publishing and viewing
- Training/learning
- Work/project management
Disabilities
These terms identify disabilities which the provision addresses.
- All disabilities
- Blindness
- Low vision
- Color deficiency/Colorblindness
- Deafness
- Hard of hearing
- Deaf-blindness
- Other combined hearing/vision loss
- Mobility
- Dexterity
- Speech
- Cognitive language/learning
- Photosensitivity (flashing)
