Spec Review

From Accessible Platform Architectures Working Group

Specifications that have been reviewed by the APA WG are listed on the Spec Review category page. Also see Technologies tracked by the APA.

Mostly APA checks specs by finding recently published specs from the Technical Reports by date page. Follow the instructions below to add a spec to the wiki for tracking. This process is most robust for finding specs that are new to the APA tracking; key status changes may not always be evident. Candidate Recommendation and later status is indicated on that page though that is often too late for meaningful review. An increasing number of specs that are routinely republished daily or weekly adds noise to this page and makes it extremely difficult to pick out meaningful publications, but a better system is not available at this time.

Repositories in the W3C organization that use the "a11y" label in their issues can support APA to find and review those issues. A list of GitHub issues labeled a11y is available.

Instructions for tracking a spec:

  • Create a page using the title of the spec.
  • Begin the page with "[[Category:Spec Review]]".
  • Optionally, add a category for the technology, such as HTML, CSS, SVG, etc.
  • Potentially, add a category for the WG developing the spec.
  • Put a link to the spec with it's full name from the title element, i.e., "[<latest version uri> | <full title including version>".
  • In a bullet list, add entries for every interaction we have with the spec, including whether we looked at it, what we decided to do, any action items taken, links to conversations with the spec developers, etc. Each bullet begins with a date in YYYY-MM-DD format.
  • As decisions are made on the spec, add / update status categories, such as:
    • Spec Review Active - review of the spec is underway via an action item or discussion;
    • Spec Review Assigned - spec has been assigned for review but not yet further discussed within the group;
    • Spec Review Complete - spec has been reviewed and any issues closed;
    • Spec Review Deferred - spec has been reviewed but needs a later review when its maturity advances;
    • Spec Review Explicit Request - spec for which we have been explicitly requested to provide comments and the response is pending;
    • Spec Review Needed - spec has been determined to need review but there isn't currently a review in process;
    • Spec Review Not Checked - spec has been added to the wiki but the group has not yet determined if it needs review;
    • Spec Review Not Needed - the group has determined the spec does not need review.
  • When completing an action to review a spec, set the action to "pending review" and send the review to the WG mailing list (by reply to the initial action email that was sent if practical). This triggers group review and next steps. Usually when the group reviews it it will be changed to "active" review or "complete" review, and in the former case a review comment prepared.
  • For funder reporting, spec review pages should have categories assigned according to the funding year in which the spec was touched. If the spec is touched in multiple funding years, provide categories for each of those years.
    • NIDILRR Year 1 - specs touched between October 2015 and September 2016
    • NIDILRR Year 2 - specs touched between October 2016 and September 2017
    • NIDILRR Year 3 - specs touched between October 2017 and September 2018
    • NIDILRR Year 4 - specs touched between October 2018 and September 2019
    • NIDILRR Year 5 - specs touched between October 2019 and September 2020