From 639e360dd3456de22f422b3135654ea273a447fc Mon Sep 17 00:00:00 2001
From: geoffroy-noel-ddh <geoffroy.noel@kcl.ac.uk>
Date: Wed, 14 Sep 2022 14:52:13 +0100
Subject: [PATCH] Improved readme.

---
 README.md       | 35 +++++++++++++++++++++--------------
 docs/index.html | 19 ++++++++++++++++---
 2 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index ff2fbb8..5341074 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,34 @@
 # Webval
 
-A [Web application](https://kingsdigitallab.github.io/webval/docs/) hosted on gthub that lets you run accessibility evaluation on multiple pages for a collection of sites. The accessibility issues are saved in this repository and can be browsed and manually annotated to facilitate accessibility assessment, review and testing processes.
+A [Web application](https://kingsdigitallab.github.io/webval/docs/) entirely hosted on github that lets you run accessibility evaluation on multiple pages for a collection of sites. The accessibility issues are saved in this repository and can be browsed and manually annotated to facilitate accessibility assessments, reviews, reporting and continuous testing.
 
-WCAG 2.1 A & AA issues are detected using Pa11y tool (html_cs engine and soon axe-core). **Note that automated detection only covers part of WCAG rules**.
+[WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) 2.1 A & AA issues are reported by [Pa11y](https://pa11y.org/) (and detected by [HTML_CodeSniffer](https://github.com/squizlabs/HTML_CodeSniffer) and [axe-core](https://github.com/dequelabs/axe-core) engines). 
+
+**Note that automated detection can only cover a minority of WCAG rules. The rest must be manually detected.**
+
+[Additional information in the wiki](https://github.com/kingsdigitallab/webval/wiki/Webval-documentation)
+
+[Report issues & suggest new features](https://github.com/kingsdigitallab/webval/issues)
 
 ## Features
 
-* The same instance can manage multiple sites and multiple pages per site (see [config file](projects/projects.json))
-* Automatically detects, store and report some of WCAG A & AA issues with details about location & problem
-* Ability to manually annotate the issues (assigning a role, complexity, resolution status and a comment)
-* Manually add issues not detected automatically 
-* Re-run automated tests on the same pages & update issues without
-losing annotations
-* Filter issues by level and resolution status
-* Summary showing the number of issues per page and level
-* Simple visual regression tests
+* The same instance can manage **multiple sites** and **multiple pages** per site (see [config file](projects/projects.json))
+* **Automatically detects, stores and reports** some of WCAG A & AA issues with details about location & problem
+* Ability to manually **annotate** the issues (assigning a role, complexity, resolution status and a comment)
+* **Manually** add and manage other issues not detected automatically 
+* **Re-run automated tests** on the same pages & update issues without losing annotations
+* Issues are **grouped by rules** for quick, high-level annotation
+* **Filter** issues by level and resolution status
+* **Summary** showing the number of issues per page and level
+* Simple **visual regression tests** 
+* Rule **tagging** system to help you categorise issues
 
 ## Architecture
 
 * Web app and all data are stored on github and run off github servers
-* Detection using Pa11y with html_codesniffer & Axe-Core engines
-* Vue.js interface with default Bulma styles
-* Regression test using Pa11y & Resemble.js
+* Detection using [Pa11y](https://pa11y.org/) with html_codesniffer & Axe-Core engines
+* Vue.js interface with default [Bulma](https://bulma.io/) styles
+* Regression test using Pa11y & [Blink-diff](https://github.com/yahoo/blink-diff)
 
 ## TODO
 
diff --git a/docs/index.html b/docs/index.html
index 0c4f3c0..fd0744f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -14,6 +14,9 @@
       window.Octokit = Octokit
     </script>    
     <style>
+      .rule-tag:hover {
+        background-color: #ffff88;
+      }
       .form-error {
         
       }
@@ -393,7 +396,7 @@ <h3 class="title is-3">Visual regression tests</h3>
         </form>
 
         <template v-if="selectedTag">
-          <h2 class="title is-2">Tags ({{ selectedTag.rules.length }} / {{ selectedRules.length }})</h2>
+          <h2 class="title is-2">Tags ({{ getRuleCountFromSelectedTag }} / {{ selectedRules.length }})</h2>
           <div class="field is-grouped bar-issues-filters">
             <div class="control">
               <button @click="onSaveTags" class="button is-primary">save</button>
@@ -415,17 +418,23 @@ <h2 class="title is-2">Tags ({{ selectedTag.rules.length }} / {{ selectedRules.l
               <button @click="onCreateTag" class="button">create</button>
             </div>
           </div>
+          <label class="label">
+            Description:
+            <input type="text" class="input" v-model="selectedTag.description">
+          </label>
 
           <table class="table">
             <tr v-for="rule in selectedRules">
-              <td>
+              <td class="rule-tag">
                 <label class="checkbox">
                   <input type="checkbox" @click="onTagRule(rule)" :checked="isRuleTagged(rule)">
                   {{ rule.code }}
                 </label>
               </td> 
               <td>{{ rule.level }}</td> 
-              <td>{{ rule.title }}</td> 
+              <td>
+                <a :href="'https://www.w3.org/WAI/WCAG21/Understanding/'+rule.id+'.html'" target="_blank">{{ rule.title }}</a>
+              </td> 
               <td>{{ rule.description }}</td>
             </tr>
           </table>
@@ -726,6 +735,10 @@ <h2 class="title is-2">Tags ({{ selectedTag.rules.length }} / {{ selectedRules.l
             selectedRules() {
               if (!this.rules) return []
               return Object.values(this.rules.rules).filter(r => this.isLevelSelected(r.level)) 
+            },
+            getRuleCountFromSelectedTag () {
+              let ret = this.selectedRules.filter(r => this.isRuleTagged(r)).length
+              return ret
             }
           },
           methods: {