rework language about audits, links to specs

Author: bollwyvl

docs/contributing.rst

@@ -321,11 +321,31 @@ Note that if needed, you can skip these checks with:
     git commit --no-verify
 
 
-Auditing accessibility
-======================
+Finding accessibility problems
+==============================
+
+The accessibility checking tools can find a number of common HTML patterns which
+assistive technology can't help users understand.
+
+In addition to `Lighthouse <https://developers.google.com/web/tools/lighthouse>`__
+in CI, the ``pa11y`` stack is installed as part of the development environment.
+
+The key components are:
 
-The accessibility checking tools are installed along with the rest of the `yarn`
-requirements. To run the accessibility auditing locally:
+- `pa11y <https://github.com/pa11y/pa11y>`__ which uses a headless browser to analyze
+  an HTML page with a configurable set of rules based on publish standards
+- `Pa11y-CI <https://github.com/pa11y/pa11y-ci>`__ runs ``pa11y`` on multiple pages
+- `pa11y-reporter-html <https://github.com/pa11y/pa11y-reporter-html>`__ generates
+  some nice HTML reports, suitable for review
+
+.. Note::
+
+    Presently, the *default* ``pa11y`` ruleset, ``WCAG2AA`` is used, a subset of
+    the `Web Content Accessibility Guidelines <https://www.w3.org/TR/WCAG21>`__.
+    The `Quick Reference <https://www.w3.org/WAI/WCAG21/quickref>`__ may provide
+    lighter reading.
+
+To run the accessibility problem finder locally:
 
 .. code-block:: bash
 
@@ -343,6 +363,11 @@ The output of the last command includes:
 Fixing accessibility errors
 ---------------------------
 
+Start by checking for issues on the
+`accessibility roadmap <https://github.com/pandas-dev/pydata-sphinx-theme/blob/master/docs/a11y-roadmap.txt>`__.
+These are issues which are currently flagged by the toolset, but that have not yet
+been fixed. If that file is empty (or just comments), hooray!
+
 To start working on one of the accessibility roadmap items, comment out one of the
 lines in `docs/a11y-roadmap.txt`, and re-run the audit to establish a baseline.