[#12081] Add user-friendliness documentation

docs/_markbind/layouts/default.md

@@ -41,12 +41,15 @@
   * [Testing]({{ baseUrl }}/best-practices/testing.html)
   * [Data Migration]({{ baseUrl }}/best-practices/data-migration.html)
   * [UI Design]({{ baseUrl }}/best-practices/ui-design.html)
+  * [Accessibility]({{ baseUrl }}/best-practices/accessibility.html)
+  * [Mobile-Friendliness]({{ baseUrl }}/best-practices/mobile-friendliness.html)
 * How-to :expanded:
   * [Captcha]({{ baseUrl }}/captcha.html)
   * [Documentation]({{ baseUrl }}/documentation.html)
   * [Emails]({{ baseUrl }}/emails.html)
   * [End-to-End Testing]({{ baseUrl }}/e2e-testing.html)
   * [Performance Testing]({{ baseUrl }}/performance-testing.html)
+  * [Accessibility Testing]({{ baseUrl }}/axe-testing.html)
   * [Search]({{ baseUrl }}/search.html)
   * [Snapshot Testing]({{ baseUrl }}/snapshot-testing.html)
   * [Static Analysis]({{ baseUrl }}/static-analysis.html)

docs/axe-testing.md

@@ -0,0 +1,30 @@
+<frontmatter>
+  title: "Accessibility Testing"
+</frontmatter>
+
+# Accessibility Testing
+
+## What is Accessibility Testing?
+
+Accessibility testing is the practice of making the application accessible to users with disabilities, who may be navigating the website using various assistive technology such as screen readers. TEAMMATES aims to be compliant to the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), and makes use of automated accessibility tests to identify a portion of WCAG rule violations.
+
+Accessibility tests in TEAMMATES can be found in the package `teammates.e2e.cases.axe`.
+
+## Running Accessibility Tests
+
+TEAMMATES uses the [axe-core](https://github.com/dequelabs/axe-core-maven-html/blob/develop/selenium/README.md) Selenium Java API for accessibility testing. Accessibility tests are set up in the same way as E2E tests. Do refer to the [E2E testing guide](e2e-testing.md#configuring-browsers-for-e2e-testing) for instructions on how to set up the tests.
+
+### Running the tests
+Accessibility tests follow this configuration:
+
+Test suite | Command | Results can be viewed in
+---|---|---
+`Accessibility tests` | `./gradlew axeTests` | `{project folder}/build/reports/axe-test/index.html`
+Any individual accessibility test | `./gradlew axeTests --tests TestClassName` | `{project folder}/build/reports/axe-test/index.html`
+
+- Before running `Accessibility tests`, it is important to have the dev server running locally first if you are testing against it.
+- When running the test cases, a few cases may fail (this can happen due to timing issues). They can be re-run until they pass without affecting the accuracy of the tests.
+
+## Creating Accessibility Tests
+
+Accessibility test classes in TEAMMATES are similar to [E2E test classes](e2e-testing.md#creating-e2e-tests) in that they inherit from `BaseE2ETestCase` and make use of page objects. The difference is that testing is conducted by running `AxeUtil.AXE_BUILDER.analyze()` on the page object's underlying browser driver.

docs/best-practices/accessibility.md

@@ -0,0 +1,31 @@
+<frontmatter>
+  title: "Best Practices: Accessibility"
+</frontmatter>
+
+# Accessibility Best Practices
+
+TEAMMATES aims to be compliant to the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). On top of the full list of WCAG gudielines, we have compiled some general guidelines below.
+
+## Content
+
+* Language used should be plan and easy to understand. Avoid using complicated figures of speech.
+* Content flow should be logical.
+* Headings should be used in a logical sequence (e.g. descending order, no skipping levels) to split the page into sections, and not used purely for visual design.
+
+## Images/Icons
+
+* Images that convey meaning should have a descriptive `alt` attribute.
+* Decorative images should have an empty `alt` attribute.
+* Icons used in controls (e.g. buttons) should have a descriptive label if they convey meaning, and should be hidden from assistive technologies (e.g. `aria-hidden` attribute set to `true`) if they are purely descriptive.
+
+## Keyboard
+
+* All interactable elements (e.g. buttons, links, inputs) should be focusable by the keyboard (e.g. when tabbing).
+* The keyboard focus/tabbing order should match the visual layout of the page.
+* Focusable elements that are hidden from the current view should be removed from the focus order.
+
+## Controls/Inputs
+
+* All inputs should have a corresponding label.
+* The contents of controls (e.g. buttons, links) and input labels should be descriptive.
+* Custom controls/inputs should have an appropriate role assigned (e.g. dropdown, button).

docs/best-practices/mobile-friendliness.md

@@ -0,0 +1,19 @@
+<frontmatter>
+  title: "Best Practices: Mobile-Friendliness"
+</frontmatter>
+
+# Mobile-Friendliness Best Practices
+
+TEAMMATES aims to be easy to use on mobile devices on top of desktop devices. Mobile-friendliness can be subjective, but we have compiled some general guidelines below.
+
+## Content
+
+* Content should be responsive to different screen sizes.
+* Content should not overflow on smaller screen sizes.
+* Horizontal scrolling should be reduced as much as possible.
+* Content should be clearly readable on smaller screen sizes.
+
+## Interactive elements (e.g. buttons, links, tooltips)
+
+* Interactive elements should be spaced far apart enough that users can easily tap them on mobile devices.
+* Tooltips that appear on hover should also be accessible on mobile devices (e.g. tap and hold).

docs/best-practices/ui-design.md

@@ -28,11 +28,12 @@ User convenience is **far** more important than developer convenience, e.g.
 * Use defaults so that users are not forced to enter values for each field. This applies to sorting as well (i.e. sort by default using the most likely sorting order).
 * If only one option is available, choose it by default.
 
-## Take user point of view
+## Take the user's point of view
 
 * Use terms from user domain.
 * Use terms that show 'user intent' rather than mechanism, e.g. 'leave this course' instead of 'delete'.
 
 ## Be consistent
 
-Use consistent naming guidelines for link, page name, page title.
+* Use consistent naming guidelines for links, page names and page titles.
+* Use consistent styles for components (e.g. buttons, links) that have the same behavior.

docs/index.md

@@ -30,14 +30,17 @@ Here are some documents important for TEAMMATES developers.
   [HTML](https://oss-generic.github.io/process/codingStandards/CodingStandard-Html.html)
 
 * **Best practices** for:
-  * [UI design](best-practices/ui-design.md)
   * [Coding](best-practices/coding.md)
   * [Testing](best-practices/testing.md)
   * [Data migration](best-practices/data-migration.md)
+  * [UI design](best-practices/ui-design.md)
+  * [Accessibility](best-practices/accessibility.md)
+  * [Mobile-friendliness](best-practices/mobile-friendliness.md)
 
 * **How-to guides** for:
   * [Static analysis](static-analysis.md): Performing code quality checks
   * [Setting up third-party email providers](emails.md)
   * [Setting up CAPTCHA](captcha.md)
   * [Snapshot testing](snapshot-testing.md)
-  * [E2E testing](e2e-testing.md)
+  * [E2E testing](e2e-testing.md)
+  * [Accessibility testing](axe-testing.md)