Tips for editing techniques

From WCAGWiki

Contents 1 Editing Techniques 2 Technique writeup checklist 3 Technique sections: 4 KNOWN FAILURE - technique Descriptions 5 Links 6 Other useful tools for techniques drafting and editing in the wiki

Editing Techniques

When editing techniques, use the Technique Template:

• copy the template into any new techniques pages
• existing techniques in wiki that don't match this format should be updated to use this format
• categorize all techniques by technology each technique page in the wiki should begin with:
  [[Category:<Tech> Techniques]] where <Tech> is replaced with CSS, General, HTML, Script, SMIL, or Server 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.

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
     - required
     - must
     - shall
  ( These words can confuse a user especially if looking at an advisory technique
    But even in a sufficient technique it must be remembered that sufficient techniques are all optional (they 
    are sufficient but not necessarily required.  There may be another method)
- The technique is written up as descriptive not imperative.  
  That is, the sentences say "with this technque you xyz"  not "do xyz".   
  The only exception is testing where the steps are imperative.

No comment about sufficiency or advisory, etc. should be in the technique document.  Again, the
information should be at the UW2 level instead.  There are several reasons for this.   
First, it is confusing to say that the technique is sufficient for a success criteria for one technique but
the same technique is not sufficient for another (because it might only be sufficient in combination).  
Also, some techniques may be sufficient in one place and advisory in another.  
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

Technique sections:

• Applicability:

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.
 - NO Baseline references
 - DOES include inforamtion on whtn it is technically appropriate to use to use the technology

 Example
 
 TABLE HEADERS
  - Applicability:   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 

• Description: 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

• Examples:

 examples of the technique in action.
 Rendered examples as well as descriptions of examples are useful
 For technology specific techniques code samples are highly recommended.

• Resources:

  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

• • Related Techniques

  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).

• Test:

 This section should describe how to test reliably that the technique has been applied,
 or that it has not been applied.

• • Procedure'

  Provide a numbered list of the steps in the testing procedure
  - be sure to not go beyond this technique. 
       (e.g. 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)

• • Expected Result

  List what should be found if the technique was successful.

• • Test Files

  ( if possible -  demonstrating Pass and demonstrating Fail)
   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 doesnt 
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."

Links

create an external link in the following manner:

[full_url_to_the_appropriate_techniques_document#ID_of_technique Title_of_technique].

For example:

[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]].

For example:

[[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).