- 1 Before you start
- 2 Editing Techniques
- 3 Technique writeup checklist
- 4 Technique sections:
- 5 KNOWN FAILURE - technique Descriptions
- 6 Links
- 7 Other useful tools for techniques drafting and editing in the wiki
Before you start
- Become familiar with the technology-neutral general techniques. Make sure the technique you are proposing is not already covered by a general technique.
- Reviewing the general techniques also helps convey a feeling for the style, structure, and scope of techniques.
- If you are proposing techniques for a specific technology, reviewing the existing technology specific techniques is similarly useful.
- For technology-specific techniques, look at the relevant standards-based techniques. Developers who are using a Web-related technology often are deploying applications or documents based on that technology within the context of a Web page. That Web page is ultimately HTML content as delivered to a Web browser user agent. There may exist equivalent techniques for addressing a specific criterion that are not general techniques, but are achievable using some combination of, say, HTML, CSS, and script. Find such techniques from the existing Understanding document sections of various criteria. You should become familiar with them. For your technology technique, you might want to compare and contrast with those existing HTML/CSS/SCR techniques. Often a technology's accessibility features are a direct response to how a particular accessibility objective might be achieved in absence of using the technology, and the technology is attempting to improve that accessibility scenario. The technology-specific technique might also represent either a widening or narrowing of support for UA or AT versus the HTML/CSS/SCR techniques.
- Consider deliberate re-use of parts of relevant general, techniques. There is nothing wrong with deliberately structuring your technique or sections thereof to resemble one or more relevant general techniques. For example, if a general technique includes an example and a test, it is appropriate to construct a very similar example within the framework of your technology, or to use similar testing steps. Re-using the same language, where possible, also helps make clear the relationship among the techniques.
- If you are proposing techniques for a specific technology, create a mapping of the criteria to techniques, as follows:
- First, list (at least) A and AA criteria.
- Then, decide whether a technology-specific technique is appropriate, at the sufficient or advisory level. As noted above, a new technique may not be required if a general technique already provides coverage. However, if there are key technical details about the technology that are relevant to applying the technology either to a general technique or to the criterion, a technique might be warranted. Whether the technique is sufficient or advisory could be suggested by how you write the technique, but that decision might ultimately be made through the review process.
- List the proposed title for the new technique or the title of the appropriate general technique next to each A/AA criterion.
- You may find it useful to add status information for each technique (Accepted, Postponed, In Review, etc.).
Consider defining a separate Technology Notes document. Depending on the technology, there might not be great familiarity with that technology on the part of the WCAG working group. Review existing Technology Notes to help decide if you need to define one.
A Technology Notes document can serve several important functions:
- Orient the WCAG working group members to aspects of the technology that will assist with the review process, specifically with being able to create test applications from the examples and verify the test procedures.
- Technology Notes become a useful place to put "applies to many/applies to all" considerations about user agents, general behavior and
assumptions, core concepts that are good to know but not necessarily well-aligned to particular criteria, cross references to Getting Started material about the overall public API, etc. If this material is placed in a single and separate document, the techniques themselves can be much more streamlined both for review purposes and for the eventual more important goal of being useful to the accessibility community.
- The concepts discussed in Technology Notes might well be some of the more complex concepts to formulate, and often take some iteration both on part of technique author and for the review process. As such, separating information into Technology Notes and either periodically reviewing the document might be helpful for the flow of reviewing a suite of specific technology techniques.
- The Technology Notes should focus on making factual points about the technology; the document should not read like it was written by the marketing group.
When editing techniques, use the Technique Template:
- copy the template into a wiki page by selecting edit on the techniques template page, selecting everything in the edit box and pasting the contents in to anew page
- categorize all techniques by technology each technique page in the wiki should begin with: [[Category:Techniques]] [[Category:<Tech> Techniques]] where <Tech> is replaced with CSS, General, HTML, Script, SMIL, Server, Flash, PDF, etc. as appropriate. (This information is in the Technique template).
- should a technique title change, select "move" in the tabbed options at the top of the page and enter the new title of the page in the input field. This moves the page to a new location, automatically preserving links from elsewhere in the wiki and retaining the history of changes.
- Techniques ready to be ported to XML should have the following in the wiki source: [[Category:Ready for XML]]
Technique writeup checklist
When you are finished with the technique, be sure that you check your writeup against this list:
- The writeup follows the guidelines below for each section.
- The following words do not appear anywhere in the writeup:
These words can confuse a user especially in an advisory technique. But even sufficient techniques are all optional. (They are sufficient but not necessarily required. There may be another method.)
- The technique is written in descriptive not imperative language. That is, the sentences say "with this technique you xyz" not "do xyz". The only exceptions are examples and test procedures where the steps are imperative.
- For technology-specific techniques, decide on a convention for referring to relevant product names and version numbers. Some products have long names that are routinely shortened (e.g., "Word"). You may elect to use the full name and version number the first time you refer to the product, and then use only the short form. For examples and test files, use the same version of products throughout technique authoring-review-approval.
- No comment about sufficiency or advisory, etc. should be in the technique document. The information should be at the Understanding WCAG2.0 level instead. There are several reasons for this:
- It is confusing to say that the technique is sufficient for a success criterion for one technique but the same technique is not sufficient for another (because it might only be sufficient in combination).
- Some techniques may be sufficient in one context and advisory in another.
- [utt: this sentence seems incomplete, hard to understand] Finally, you can end up with something where the techniques document differs from the understanding document is too hard for people to review and make sure they have things correct if the information is in multiple places and not exactly the same.
- Special notes for common failure techniques docs are provided at the end of the regular notes.
- Be aware of possible AND relationships. In some cases, new techniques that are added sufficient/advisory sections for criteria should be declared in an AND relationship with a general technique. In this case it is particularly important to thoroughly comprehend the general technique in question, and confirm that your technique is appropriate for the AND relationship. During the review process, it might be helpful to suggest a possible AND relationship so that the technique's contents can be reviewed in that context.
Includes information on when it is technically appropriate to use the technique:
- DO NOT include information on when you should or should not use the technique for accessibility or conformance.
- Use NO Baseline references. [utt: what does this mean?]
- DO include information on when it is technically appropriate to use or not use the technology
For example, a technique on table headers might say:
Use for data tables but not for layout tables (ref HTML 4.01)
User Agent and Assistive Technology Support Notes
Include Notes on any known issues regarding lack of support for this technique with commonly used user agents or assistive technologies.
Do not include this title on General Techniques.
This is the main content of the technique. Start with a sentence saying "the objective of this technique is..." Follow that with information necessary to understand what they are trying to achieve and how to carry out the technique.
Perhaps the single most important content of a technique is the first sentence that clarifies the objective of the technique, immediately following the Description heading. That objective should be stated succinctly; and keep in mind that applying the technique will reach the objective. Any fine points of reaching the objective might best be addressed in a subsequent paragraph, subhead of Description, or in other sections. Refer to your review of general and other techniques for examples; if your technique achieves the same objective as, say, a general technique but with specific technology, re-use the objective and other relevant text in your Description.
Provide numbered examples of the technique in action. Rendered examples [utt: what is this?] as well as descriptions of examples are useful. For technology specific techniques, code samples are highly recommended. Some pointers:
- Provide simple examples that focus on method(s) to achieve the technique's objective. It may be tempting to provide more "real-world" examples, or to use the same example code to illustrate multiple techniques, but focus on the objective is best. Readers should be able to scan the examples for basic understanding. Real-world examples could be indicated as a Reference or as an inline reference in the Example explanatory introduction.
- If multiple examples, or even multiple techniques for the SAME criterion, are appropriate because the technology facilitates multiple ways, it may be helpful to align the relevant examples so that testing those examples produces a similar result either visually or behaviorally.
- Create your own examples and test them using the instructions from the example text. Supply the files required to re-create the example to the working group to aid their review; likely these files will be needed to provide test files in the published technique.
- Provide user instructions for the examples using numbered steps and the imperative voice; e.g., "Select the File menu."
- Use device neutral terminology for accessibility; e.g., use "select" rather than "click on."
- Provide screen shots of key intermediate steps in the example and the result. Make sure each image has an accessible text alternative.
Links to free resources that:
- support the technique
- provide educational information
- are Public-Domain Test tools for this Technique
- citations of specific sections of standards related to this technique
This should include only closely related techniques such as techniques for going beyond what this technique requires. For example, the technique for attaching short text alternatives may also list general techniques for the content of the text alternative (i.e. writing good text alternatives).
This section should describe how to test reliably that the technique has been applied, or that it has not been applied.
- Provide a numbered list of the steps in the testing procedure.
- Authors are encouraged to provide at least one test procedure that does not require specific tool/technology (e.g., code-level procedure) but authors are permitted to provide test procedures that rely on a specific tool/technology.
- Be sure to not go beyond this technique. For instance, if it is a technique to attach alternate text, do not talk about sufficiency of the text (which is covered by another technique),just test to see that it is there.
- Test procedures may be one of two types:
- AND: multiple steps/tests, all must pass. Example:
PROCEDURE: 1. Using the keyboard, make sure... 2. Using a tool that exposes the accessibility API, make sure... EXPECTED RESULTS: Check #1 and Check #2 are true.
- OR: one step/test, several ways to pass, any one of the list of possibilities is sufficient. Example:
PROCEDURE: 1. For each list in the PDF document, verify list structure in one of the following ways: - Read the document with a screen reader... - Inspect the tag tree... - Using a tool that exposes... EXPECTED RESULTS Check #1 is true.
List what should be found if the technique was successful (see above).
If possible, demonstrating Pass and demonstrating Fail. See notes above in Examples for test file suggestions.
There are no test files for general techniques and this section is skipped.
NOTE: "Related tests" should not be included or linked to. Each of those tests is actually a test of another technique. They may be needed for sufficiency, may be part of a different sufficiency set (and therefore not needed with this technique to satisfy sufficiency), or may be advisory (optional). To avoid confusion they should not be linked to from this technique. Instead each technique (and its included test) should be linked to from the appropriate point in the Understanding WCAG 2.0 document.
KNOWN FAILURE - technique Descriptions
These technique descriptions need to be done with particular care to make user that they are clearly failures. Also, stating that something is a failure is close to 'requiring' something for conformance - which we cannot do it a technique. Therefore the failure must always be stated in terms of the success criteria wording itself. It should also be a statement of fact, not a statement of failure.
For example, in 1.1.1 there is a failure due to text not being a text alternative. Since text alternatives are required in the sc language, this is clearly not going larger or smaller than the sc. The failures then are just statements of things that are clearly not text alternatives (facts). The example section doesn't say that these are failures; just that they are not text alternatives. Then the test section doesnt talk about passing or failing the technique. (what does it mean to fail a failure technique). Instead it says: "If any are found then this failure condition applies and content fails the success criterion."
Create an external link in the following manner:
[http://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-HTML-TECHS-20051123/Overview.html#H62 Using the body of the <span> <code>applet</code> </span> element].
Create a link to an existing wiki page by enclosing the page name in double square brackets: [[page name]].
[[Searching an on-line dictionary]]
Other useful tools for techniques drafting and editing in the wiki
- Complete list of How to Meet docs
- Complete list of Techniques
- techniques in wiki should be reviewed for appropriateness for each success criterion
- uncreated techniques (links appear in red) should be created as necessary using the Technique Template
- Published techniques that are not in the wiki have an arrow beside the link. These should only be moved into the wiki if edits are needed. Create the new page with a name that matches the title of the existing technique and only copy over the sections where proposed changes/additions are being made. Include a pointer to the latest published draft as appropriate.
- Review the SC to techniques mapping from the 30 June 2005 draft to find previously drafted techniques that relate to the relevant How to Meet document.
- is the title/page name info correct? You can use the HTML::WikiConverter to import the technique into the wiki and make the edits.
- add links to other techniques as appropriate
- check unmapped techniques in orphaned pages to see if any of them should be linked into appropriate How to Meet docs
- review for quality
- when viewing a technique, use "what links here" (in "tools" box) to determine if a technique is referenced to the appropriate How to Meet document(s).