Writing WCAG Techniques - Notes
How do Techniques Help People Understand WCAG
- Specific examples of the general language of the guidelines
- Best Practices
- Worse Practices that still meet WCAG
Describe the Outcome, not the Process
- Developers & evaluators
- Can result in awkward language, passive voice, etc
Sections of a Technique
See Michael’s excellent write-ups, Technique Instructions and Technique Template. Open the Technique Template for edit, copy it, and paste it into your new technique wiki page. Then, edit it into the new technique, following the guidance in the template.
- Technique new, or revised version of existing technique?
- Links to surveys where the technique has been reviewed; status of handling comments from surveys.
- What technologies does this technique use? On a particular type of content?
- Which success criteria does it relate to, either as a sufficient or advisory technique.
User Agent and Assistive Technology Notes
What do we know at this time about the status of AT support for this technique? In the published technique, this will move into the accessibility support database. If it doesn’t, at least date the information since it gets stale quickly.
Traditionally, we have only published notes about AT/browser combinations that we knew about that fail to support the technique. Our testing has been very English-language oriented.
“The objective of this technique…” describes what the technique is trying to accomplish. The bulk of the description should describe HOW to accomplish that end. Except sometimes for General Techniques, it is not sufficient just to describe the result. Your audience is a developer or evaluator who wants to apply this technique but does not understand how.
If all you have is the finished page, how do you know that the technique was used?
It is also not sufficient to rely on the examples for the technical details. It is never clear whether an example covers everything involved in every application of the technique.
Descriptions can also include discussions of best practice, but be clear about the difference between best practice and what is the minimum required to apply the technique.
Very useful for helping people understand the technique. The code from examples may be cut-and-pasted into web pages.
Complete, WCAG-compliant examples can be long and complex, and involve lots of code that isn’t addressing the success criteria at hand. This can make it hard for readers to understand the critical part of the example for this technique.
We try to compromise by just including the relevant parts of the example in the code snippets of the example, but providing a link to a live example that contains the complete code.
The expectation that there will be live examples is relatively recent. Lots of existing techniques don’t link to live examples at all.
Don’t include Failure Examples, that is, code that doesn’t apply the technique (even though they can be valuable for discussing why they failure example doesn’t meet the technique). People won’t be paying attention, and they’ll copy the code as if it is a positive example.
Any resources on the web that might be helpful to someone working with this technique. This may include relevant specs, blog article that discuss this or a related technique, etc.
Related Techniques is a subsection of Resources, and lists techniques that are alternatives to this technique, or failures that are relevant.
This section contains 2 parts, the test Procedure and the Expected Results.
The procedure should list steps to take to evaluate whether this technique is being used. It can include multiple steps. At least some should be checks: “Check that X is true” or “Check that Y is false”. The steps should be as clear as possible and should not rely on the reader’s judgment. The test defines the technique, at some level.
The Expected Results capture what outcomes are needed from the Check steps to determine whether the technique has been applied. They can be complex expressions, but the more straightforward they are, the easier the test procedure and the technique will be to understand.
Sometimes, especially for General Techniques, the test steps are functional: do this, and see whether the outcome is that. Functional tests of this type should be avoided whenever possible, because their outcome can be heavily influenced by accessibility support issues. This makes it hard for the developer and the evaluator to tell whether the technique has been applied properly, and it means that the test results may be inconsistent, depending upon what particular combination of browser and AT was used in running the test.
Goal was only to document common failures, to help people avoid them.
Failures are stronger than techniques:
- In the opinion of the WG, they represent patterns that fail WCAG
- No accessibility support considerations
- You can always use a different technique, but failures are universal
- Evaluators love failures
Awkward to write up, and should be clearly labeled as Failure Examples.
Also awkward. The expected results are even more confusing, which is why the template for a failure Expected Results is “If XXX, then this failure condition applies and the content fails the success criteria.”