Update documents to reflect ACT format latest draft (#69)

* Update documents to reflect ACT format latest draft

* Editorial page updates

* Alight templates with ACT-RF

* Remove redundant ruleId field

_layouts/default.html

@@ -147,9 +147,6 @@ <h2>Rule Structure</h2>
       <li><a href="{{ site.baseurl }}/pages/structure/aggregation.html">
         Result aggregation
       </a></li>
-      <li><a href="{{ site.baseurl }}/pages/structure/user-questions.html">
-        User questions
-      </a></li>
       <li><a href="{{ site.baseurl }}/pages/structure/accessibility-support.html">
         Accessibility support
       </a></li>

_layouts/rule.html

@@ -2,8 +2,12 @@
 layout: default
 ---
 
+{% assign ruleId = page.url | remove: "/rules/" | remove: "/drafts/" | remove: ".html" %}
 {% if page.draft %}
+  {% assign status = "draft" %}
   <p class="draft-note"><strong>Please note, this is a draft</strong></p>
+{% else %}
+  {% assign status = "rule" %}
 {% endif %}
 
 {% if page.date %}
@@ -17,7 +21,7 @@
       	site.data.contributors[author].name
     }}</a>{%
   	  else
-  	%}{{  author  }}{%
+  	%}{{ author }}{%
 	  endif
 	%}{%
 	  if forloop.last == false
@@ -26,4 +30,50 @@
   %}{% endfor %}</p>
 {% endif %}
 
+{% if page.description %}
+  <h2 id="description">Description</h2>
+  <p>{{ page.description | markdownify }}</p>
+{% endif %}
+
+{% if page.success_criterion %}
+  <h2 id="requirements">Accessibility Requirements</h2>
+  <p>This conformance rule relates to:</p>
+  <ul>
+  {% for critId in page.success_criterion %}
+    {% assign criterion = site.data.criteria[critId] %}
+    <li>
+      <a href="https://www.w3.org/TR/WCAG20/#{{ criterion.id }}">
+        Success Criterion {{ criterion.num }} ({{ criterion.handle }})
+      </a>
+      <ul>
+        <li><a href="https://www.w3.org/WAI/WCAG20/quickref/#{{ criterion.id }}">
+          How to Meet {{ criterion.num }} ({{ criterion.handle }})
+        </a></li>
+        <li><a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/{{ criterion.id }}.html">
+          Understanding Success Criterion {{ criterion.num }} ({{ criterion.handle }})
+        </a></li>
+      </ul>
+    </li>
+  {% endfor %}
+  </ul>
+{% endif %}
+
 {{ content }}
+
+{% if page.test_aspects %}
+  <h2 id="test-aspects">Test Aspects</h2>
+  Test aspects are defined as part of the <a href="https://w3c.github.io/wcag-act/act-rules-format.html#input-aspects-common">ACT Rules format 1.0</a>.
+  <ul>
+  {% for aspect in page.test_aspects %}
+    <li>{{ aspect | markdownify }}</li>
+  {% endfor %}
+  </ul>
+{% endif %}
+
+<h2 id="related-resources">Related Resources</h2>
+<ul>
+  <li><a href="../{{status}}-tests/{{ ruleId }}.test.html">Test cases</a></li>
+  <li><a href="https://github.com/auto-wcag/auto-wcag/issues?q=is%3Aopen+is%3Aissue+{{ ruleId }}">Known issues</a></li>
+  <li><a href="https://github.com/auto-wcag/auto-wcag/commits/master/_{{status}}s/{{ ruleId }}.md">Previous versions</a></li>
+  <li><a href="https://github.com/auto-wcag/auto-wcag/edit/master/_drafts/{{ ruleId }}.md">Propose an update</a></li>
+</ul>

pages/about.md

@@ -11,7 +11,7 @@ Web accessibility testing is highly reliant on human judgment. Not only that, bu
 
 The objective of this community is to create and maintain rules to test WCAG, that can be used to test and monitor web accessibility in a scalable manner. These rules will be either automated, or semi-automated, in which tools assist non-expert users to evaluate web accessibility. The rules consist of small, atomic test steps that look if specific elements on a web page meet WCAG 2 success criteria.
 
-Each rule has a selector, looking for one ‘type’ of content on a web page. This piece of content is then run through a series of automatic or manual steps. For each element found in the selector, a rule will indicate if it passed of failed.
+Each rule has a certain applicability, targeting one ‘type’ of content on a web page. This piece of content is then tested against a series of automatic or manual expectations. For each applicable element a rule will indicate if it passed of failed.
 
 By comparing the test results with results from expert accessibility evaluators, we aim to track the accuracy of the tests we’ve developed. This allows us for an iterative improvement and adjustment of the tests as web development practices change and evolve.
 

pages/contribute.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Ccontribute to Auto-WCAG
+title: Contribute to Auto-WCAG
 ---
 
 Auto-WCAG is a group open to anyone interested in accessibility, accessibility testing or automated testing. We welcome contributions from anyone, either though Github issues and pull requests, or by contribution to our monthly teleconferences.
@@ -21,8 +21,8 @@ The best way to stay informed about the activities of Auto-WCAG is to become a m
    This request will be sent to your organization's representative in the W3C's
    Advisory Committee.
 
-## Participate in our montly calls
+## Participate in our monthly calls
 
-Auto-WCAG has conference calls every 4 weeks on Thursdays at 16:00 Central European Time. Participating in these calls is the easiest way to become an active contributor. The invitation and agenda for these meetings is sent out through the mailing list a few days in advance.
+Auto-WCAG has conference calls every month (usually) on the second Thursdays at 16:00 Central European Time. Participating in these calls is the easiest way to become an active contributor. The invitation and agenda for these meetings is sent out through the mailing list a few days in advance.
 
 

pages/design/review.md

@@ -12,7 +12,7 @@ When a proposal in step 1 is done, a pull request is created to update the rule
 
 1. Editorial comments can be resolved immediately by updating the pull request. 
 
-2. For any comments that can't be resolved immediately, a new issue is created. Once the pull request is discussed during an Auto-WCAG call, the pull request is merged in. The team working on this rule continues working on the new issue that was created, going back to step 1.
+2. For comments that can't be resolved immediately, a new issue is created. Once the pull request is discussed during an Auto-WCAG call, the pull request is merged in. The team working on this rule continues working on the new issue that was created, going back to step 1.
 
 3. If no comments come in, the issue can be merged in after it has been discussed on an Auto-WCAG call. If the authors feel the rule is ready for publication, and they have merged the pull request into draft, they can open a new pull request, which must have "FINAL" in the pull request name, to move the rule from `_drafts` to `_rules`. This will publish the rule. The rule needs at least **3 approved votes** before it can be merged from people who weren't the editors. If new comments come in, the pull request must be closed without merging, and a new issue is created to work on the fix.
 

pages/design/rule-design.md

@@ -2,126 +2,71 @@
 title: Rule Design
 ---
 
-The Auto-WCAG rule design builds on WCAG 2.0 and its supporting documents. To achieve the Auto-WCAG goals the following approach is suggested:
+The Auto-WCAG rule design builds on WCAG 2.x and its supporting documents. To achieve the Auto-WCAG goals the following approach is suggested:
 
-1. **Rule identifier**: The identifier for the rule
+1. **[Rule properties](#rule-properties)**: Define the test subject and its environment, as well as other meta data.
 
 2. **Description**: Brief description of what the rule does
 
 3. **Background**: A list of resources that support the workings of the rule.
 
 4. **[Assumptions](#assumptions)**: Explicitly state all assumptions made by the rule to ensure accountability of the results.
 
-5. **[Rule properties](#rule-properties)**: Define the test subject and its environment, as well as other meta data.
+5. **[Applicability](#applicability)**: Identify which elements on a page (if any) are to be tested using the rule.
 
-6. **[Selector](#selector)**: Use selectors to group the tests by page element and Success Criterion.
+6. **[Expectations](#expectations)**: Assert what must be true about the target elements, in order for them to pass the rule.
 
-- **[Test steps](#test-steps)**: Describe complete flow and testing logic, i.e. test procedures that can reach a conclusion if the web content passes or fails a Success Criterion.
+## Rule Properties
 
-## Rule identifier
+### Rule name and identifier
 
-For the name of the test case use the following format: **SC#-#-#-identifier**
+The rule must have a unique name, preferably a two or three word topic, as well as an identifier. This uses the following format: **SC#-#-#-identifier**
 
 - **SC#-#-#**: This is an identifier for the criterion to which the test case applies. #-#-# stands for the number of that criterion, such as SC4-1-2.
 
 - **+SC#-#-#**: This can be used if the test case applies to multiple success criteria, such as SC1-1-1+SC4-1-2-identifier. The numbers are in the same order as they are used in WCAG.
 
 - **identifier**: This must be a lower case identifier of the test, preferably no more then 3 words. It can only contain alphanumeric values or a dash (-).
 
-## Assumptions
-
-Many accessibility evaluations (especially automated tools) make assumptions about the structure of the web content and the way in which (web) technologies are used. Such assumptions influence the outcome of a test. If the assumptions are made implicitly, it will be difficult to interpret the test result. Comparability and reproduction of results by other tools are limited. Therefore the Auto-WCAG test include a list of all assumptions made by the design of the rule.
-
-> *For example:* A rule for 1.4.1 Use of Color has to make an assumption with CSS-properties are used to make a link visually evident. Typically something like `background`, `border`, `color`, `font`, or `text-decoration`.
-
-While most assumptions relate to the rule itself, there are some assumptions that apply at other stages of the evaluation:
-
-- It is assumed that the tested web page is the one that has to conform to WCAG 2.0 and that there is no [conforming alternative version](http://www.w3.org/TR/WCAG20/#conforming-alternate-versiondef).
-
-- It is assumed that the following technologies are accessibility supported: HTML, CSS, WAI-ARIA, ... (See also Auto-WCAG's [explanation on Accessibility Support](accessibility-support.html)).
-
-## Rule properties
-
-The Auto-WCAG rules indicate the subject to which the test is applied and describe the environment in which the test is carried out. (See also: **WAET** [Retrieving and rendering web content](http://www.w3.org/TR/2014/WD-WAET-20140724/#subjects))
-
-### Test environment
-
-The **environment** specifies how tools must pre-process the web content before the test is applied.
-
-*Example**: An HTML grammar check is carried out on the unprocessed HTML source. Tests that check the color contrast must be applied on the DOM and CSS.
+### Test aspects
 
-The environment is one of:
+A test aspect is a part of a test subject that must be available in order to properly run the test. The ACT Rules Format defines the following:
 
-- **HTML source**: Unprocessed source of the web page
-- **DOM tree**: Generated source after onload scripts are applied (no user interaction). CSS is taken into account so that elements that are not displayed are not tested.
-- **DOM and CSS**: Same as 2. plus computed style for each element)=
-- **Rendered page**: Page as it is presented in a browser
-- **Rendered page + server connection**: Page as it is presented in a browser, as well as an open connection (and any cookies or other session data that might be required)
+- HTTP Messages: All messages sent through HTTP(S)
+- DOM Tree: The tree that HTML is parsed into
+- CSS Styling: CSS applied to lay out and style the DOM Tree
+- Accessibility Tree: The tree that user agents expose to the accessibility API
 
-**Note**: The rule should specify the minimum level of pre-processing. A test that is carried out on the DOM can usually also be carried out on the rendered page but the the latter needs more processing power. It should also be kept in mind that the use of a (headless) browser can introduce bugs in the test procedure.
+Other aspects may be necessary for testing. These can be added as long as they are sufficiently defined.
 
-### Test subject
+### Authors
 
-The **subject** determines which parts of a web page or web site must be analysed to carry out the test.
+Names of the Authors. These must be an exact match of names in `_data/contributors.yml`.
 
-> Example:
-> A test that checks for labels in a form can be carried out on the respective DOM fragment. A test for consistent navigation must take into account multiple pages.
-
-The subject is one of:
-
-- single web page
-- multiple web pages
-- web page state
-- DOM document fragment
-
-*Note* that the test description should specify the minimum level.
-
-### Assertor requirements (optional)
-
-For each step of a test procedure (including the selection step) the auto-wcag tests describe if the step is carried out by a tool or by a human evaluator.
-
-If the step is carried out by a human evaluator, the level of expertise can be specified:
-
-1. no prior knowledge
-2. basic understanding of HTML
-3. basic understanding of HTML and WCAG
-4. advanced understanding of HTML and WCAG
-
-If the step is carried out by a tool, the required processing capabilities can be specified.
-
-## Selector
-
-The selectors add structure to the set of tests and provide additional details for the implementation in automated test tools.
+## Assumptions
 
-For each Success Criterion the page elements that have to be checked are identified. The tests are grouped by page element.
+Many accessibility evaluations (especially automated tools) make assumptions about the structure of the web content and the way in which (web) technologies are used. Such assumptions influence the outcome of a test. If the assumptions are made implicitly, it will be difficult to interpret the test result. Comparability and reproduction of results by other tools are limited. Therefore the Auto-WCAG test include a list of all assumptions made by the design of the rule.
 
-The selectors are **disjoint**, i.e. each elements is matched by at most one selector per SC.
+> *For example:* A rule for 1.4.1 Use of Color has to make an assumption with CSS-properties are used to make a link visually evident. Typically something like `background`, `border`, `color`, `font`, or `text-decoration`.
 
-> *Example*: Success criterion 1.4.1 Use of Color might have the following selectors:
->
-> - links within text
-> - form elements
-> - other text
-> - images
+While most assumptions relate to the rule itself, there are some assumptions that apply at other stages of the evaluation:
 
-The Auto-WCAG will describe separate tests for each of these cases. The cases are derived from the WCAG 2.0 Success Criteria and the Techniques for WCAG 2.0.
+- It is assumed that the tested web page is the one that has to conform to WCAG 2.0 and that there is no [conforming alternative version](http://www.w3.org/TR/WCAG20/#conforming-alternate-versiondef).
 
-The selectors must be **unambiguous**. Whenever possible selectors should be given in a machine-readable way. So that the subject of the test can be identified automatically (and thus be subject to sampling if needed). This approach supports less experienced evaluators because the test subject can be presented together with the relevant steps of the test procedure. In some cases the selection can't be done by a tool because human judgment is required. This is also be stated in the test description.
+- It is assumed that the following technologies are accessibility supported: HTML, CSS, WAI-ARIA, ... (See also Auto-WCAG's [explanation on Accessibility Support](accessibility-support.html)).
 
-The following options for **machine-readable** selectors used by Auto-WCAG:
+## Applicability
 
-- **CSS selectors**:
-  1. W3C Recommendation: [http://www.w3.org/TR/css3-selectors/ Selectors Level 3].
-  2. Work in progress [Selectors Level 4](http://www.w3.org/TR/2013/WD-selectors4-20130502/) and [Non-element Selectors Module Level 1](http://www.w3.org/TR/2014/WD-selectors-nonelement-1-20140603/)
+Applicability describes which (elements of) web pages should be tested using the rule. These elements are known as test targets. Applicability must be written in plain language, so that it can be used by QA testers. Applicability must rely on well defined properties of the technologies that are tested. For example, a rule may be applicable to all `video` elements, but it can not be applicable to all `object` elements used to show video, unless the term "video" is further defined.
 
-- **HTML 5**: Algorithmic selectors as described in [The elements of HTML](http://www.w3.org/TR/html5/semantics.html#semantics)
+Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. The intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. 
 
-- **XPath**: W3C Recommendation: [XML Path Language (XPath) 3.0](http://www.w3.org/TR/xpath-30/)
+For more details, see [ACT Rules Format: Applicability](https://w3c.github.io/wcag-act/act-rules-format.html#applicability)
 
-**Note**: Selectors are used to trigger a test. They should not be confused with ways to identify an element in the report/test results. The latter will be expressed as a Test Result, in particular the `earl:pointer` property.
+## Expectations
 
-## Test steps
+The applicability help the testers (or test tools) identify what has to be checked. Following that, the expectations are statements that must be true for the applicable elements to pass the rule. If any of the expectations is false, than the target element failed the rule. 
 
-The selectors help the user (or tool) identify what has to be checked. The goal of the Auto-WCAG test design is to cover the complete workflow, i.e. all steps / all tests that are necessary to reach a conclusion. The procedure contains automated and manual steps. Usually a combination of both.
+Each expectation exposes a reason why an element may not meet a particular conformance requirement. The expectations can be "linked", in that one has to be met before a second can be tested. For example, a rule testing link names may have as its first expectation "Target element has an accessible name", and as a second expectation "Expectation 1 is true for the target element, and the accessible name describes the function of the target element".
 
-The results for the individual steps / tests are combined to reach a conclusion about the success criterion. All success criteria use the same [basic aggregation algorithm](/pages/structure/aggregation.html).
+For more details, see [ACT Rules Format: Expectations](https://w3c.github.io/wcag-act/act-rules-format.html#expectations)