docs: tweak docs

guidepup · Jan 26, 2024 · fc29a32 · fc29a32
1 parent ae9ab9f
commit fc29a32
Show file tree

Hide file tree

Showing 10 changed files with 46 additions and 41 deletions.
diff --git a/docs/example.md b/docs/example.md
@@ -132,7 +132,7 @@ For this example we are using the recommended configuration from the Guidepup Pl
 
 In addition to recommended configuration, we also set a long timeout and disable slow test warnings as automating VoiceOver is slightly slower than Playwright expects if simply automating the browser.
 
-We also setup some retry configuration, and let Playwright know that we want to test against WebKit in headed mode with video recording switched on.
+We also set up some retry configuration, and let Playwright know that we want to test against WebKit in headed mode with video recording switched on.
 
 ## Create Test File {#test}
 
@@ -164,7 +164,6 @@ test.describe("Playwright VoiceOver", () => {
 
     // Wait for page to be ready
     await expect(page.locator('header[role="banner"]')).toBeVisible();
-    await voiceOver.interact();
 
     // Interact with the page
     await voiceOver.navigateToWebContent();

diff --git a/docs/guides/automated-environment-setup.md b/docs/guides/automated-environment-setup.md
@@ -6,7 +6,9 @@ description: Environment setup guidance for automating screen readers for access
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-This guide applies to users of the [`@guidepup/guidepup`](https://github.com/guidepup/guidepup) or [`@guidepup/playwright`](https://github.com/guidepup/guidepup-playwright) packages. OS environment setup is not required for users of the [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader) package.
+This guide applies to users of the [`@guidepup/guidepup`](https://github.com/guidepup/guidepup) or [`@guidepup/playwright`](https://github.com/guidepup/guidepup-playwright) packages.
+
+OS environment set up <em>is not required</em> for users of the [`@guidepup/virtual-screen-reader`](https://github.com/guidepup/virtual-screen-reader) package.
 
 ## Automated Setup
 
@@ -38,7 +40,7 @@ npx @guidepup/setup --ci
 </TabItem>
 </Tabs>
 
-The CLI will first attempt to configure your environment itself, but on systems with tighter security controls such as MacOS with [System Integrity Protection (SIP)](https://support.apple.com/en-gb/HT204899), it may prompt you for additional inputs such as username and password so that it can complete setup through UI automation.
+The CLI will first attempt to configure your environment itself, but on systems with tighter security controls such as MacOS with [System Integrity Protection (SIP)](https://support.apple.com/en-gb/HT204899), it may prompt you for additional inputs such as username and password so that it can complete the setup through UI automation.
 
 If you are uncomfortable with providing credentials to this CLI you can manually achieve these steps by following the [Manual VoiceOver Setup](/docs/guides/manual-voiceover-setup) guide.
 

diff --git a/docs/guides/manual-voiceover-setup.md b/docs/guides/manual-voiceover-setup.md
@@ -5,7 +5,7 @@ title: "Manual VoiceOver Setup"
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-If [`@guidepup/setup`](https://github.com/guidepup/setup) cannot be used for your MacOS workflow, these guides instruct how to setup your MacOS environment manually for VoiceOver automation.
+If [`@guidepup/setup`](https://github.com/guidepup/setup) cannot be used for your MacOS workflow, these guides instruct how to set up your MacOS environment manually for VoiceOver automation.
 
 ## Local Setup
 

diff --git a/docs/intro.md b/docs/intro.md
@@ -28,19 +28,19 @@ npx @guidepup/setup
 
 For some operating systems, enabling automation of screen readers is tightly controlled. This CLI handles the setup for your OS.
 
-For further information checkout this [guide to setup your environment](./guides/automated-environment-setup).
+For further information checkout this [guide to set up your environment](./guides/automated-environment-setup).
 
 ## Installation {#installation}
 
 Install Guidepup to your project:
 
 <Tabs
-  groupId="pm-flavor"
-  defaultValue="yarn"
-  values={[
-    {label: 'Yarn', value: 'yarn'},
-    {label: 'NPM', value: 'npm'}
-  ]
+groupId="pm-flavor"
+defaultValue="yarn"
+values={[
+{label: 'Yarn', value: 'yarn'},
+{label: 'NPM', value: 'npm'}
+]
 }>
 <TabItem value="yarn">
 
@@ -65,12 +65,12 @@ Let's automate a screen reader!
 Create `example.js` (or `example.ts` for TypeScript) to define your screen reader code.
 
 <Tabs
-  groupId="js-flavor"
-  defaultValue="ts"
-  values={[
-    {label: 'Typescript', value: 'ts'},
-    {label: 'JavaScript', value: 'js'},
-  ]
+groupId="js-flavor"
+defaultValue="ts"
+values={[
+{label: 'Typescript', value: 'ts'},
+{label: 'JavaScript', value: 'js'},
+]
 }>
 <TabItem value="ts">
 
@@ -151,12 +151,12 @@ const { nvda } = require("@guidepup/guidepup");
 Now run your code to see an automated screen reader!
 
 <Tabs
-  groupId="js-flavor"
-  defaultValue="ts"
-  values={[
-    {label: 'TypeScript', value: 'ts'},
-    {label: 'JavaScript', value: 'js'}
-  ]
+groupId="js-flavor"
+defaultValue="ts"
+values={[
+{label: 'TypeScript', value: 'ts'},
+{label: 'JavaScript', value: 'js'}
+]
 }>
 <TabItem value="ts">
 
@@ -172,4 +172,4 @@ node example.js
 ```
 
 </TabItem>
-</Tabs>
+</Tabs>
diff --git a/docs/release.md b/docs/release.md
@@ -6,4 +6,6 @@ description: Release notes for the Guidepup screen reader driver for accessibili
 - `@guidepup/guidepup` - [https://github.com/guidepup/guidepup/releases](https://github.com/guidepup/guidepup/releases).
 - `@guidepup/playwright` - [https://github.com/guidepup/guidepup-playwright/releases](https://github.com/guidepup/guidepup-playwright/releases).
 - `@guidepup/virtual-screen-reader` - [https://github.com/guidepup/virtual-screen-reader/releases](https://github.com/guidepup/virtual-screen-reader/releases).
+- `@guidepup/jest` - [https://github.com/guidepup/jest/releases](https://github.com/guidepup/jest/releases).
 - `@guidepup/setup` - [https://github.com/guidepup/setup/releases](https://github.com/guidepup/setup/releases).
+- `guidepup/setup-action` - [https://github.com/guidepup/setup-action/releases](https://github.com/guidepup/setup-action/releases).
diff --git a/docs/support.md b/docs/support.md
@@ -34,7 +34,9 @@ To learn NVDA commands please refer to the following popular guides:
 
 The Guidepup [Virtual Screen Reader](https://github.com/guidepup/virtual-screen-reader) is a headless screen reader for unit test automation.
 
-- **Mirrors Real User Experience** - assert on what users really do and hear when using screen readers.
+- **Mirrors Screen Reader Functionality** - simulate and assert on what users can do when using screen readers.
 - **Test Framework Agnostic** - run with Jest, with Playwright, as an independent script, no vendor lock-in.
 - **UI Framework Agnostic** - want to use React, Vue, Solid, Svelte, etc.? All good here! Works with any UI framework, and plays nicely with the [Testing Library](https://testing-library.com/) suite.
-- **Fast Feedback** - avoid the cumbersome overhead of running an e2e test with a running screen reader by running virtually over the provided DOM.
+- **Fast Feedback** - avoid the cumbersome overhead of running an e2e test with a running screen reader by running virtually over the provided DOM.
+
+> Note: This package should not replace your manual screen reader testing, there is no substitute for testing with real screen readers and with real users.
diff --git a/src/components/HomepageFeatures/index.js b/src/components/HomepageFeatures/index.js
@@ -3,19 +3,21 @@ import styles from "./index.module.css";
 
 const FeatureList = [
   {
-    title: "Full Control",
+    title: "Full control",
     description: (
-      <>If the VoiceOver or NVDA screen readers have a keyboard command, then Guidepup supports it.</>
+      <>
+        If VoiceOver or NVDA have a keyboard command, then Guidepup supports it.
+      </>
     ),
   },
   {
-    title: "Mirrors Real User Experience",
+    title: "Mirrors real user experience",
     description: (
       <>Assert on what users really do and hear when using screen readers.</>
     ),
   },
   {
-    title: "Framework Agnostic",
+    title: "Framework agnostic",
     description: (
       <>
         Run with Jest, with Playwright, as an independent script, no vendor

diff --git a/src/components/HomepageFeatures/index.module.css b/src/components/HomepageFeatures/index.module.css
@@ -4,3 +4,7 @@
   padding: 2rem 0;
   width: 100%;
 }
+
+.features h3 {
+  text-transform: capitalize;
+}
diff --git a/src/pages/index.js b/src/pages/index.js
@@ -37,16 +37,9 @@ function HomepageTagline() {
         )}
       >
         <h2 className="text--center">
-          <b>Reliable</b> Automation For Your{" "}
-          <b>Screen Reader A11y Workflows</b> Through JavaScript
+          <span>Reliable</span> automation for your{" "}
+          <span>screen reader a11y workflows</span> through JavaScript
         </h2>
-        <p className="text--center">
-          A11y static analysis tools only cover around 25% of WCAG and don't assure on
-          the quality of the user experience for screen reader users. This means
-          teams need to perform lots of manual tests with multiple screen
-          readers to ensure great UX which can take a lot of time...{" "}
-          <b>not anymore!</b>
-        </p>
         <p className="text--center">
           With Guidepup you can automate your screen reader test workflows the
           same you as would for mouse or keyboard based scenarios, no sweat!

diff --git a/src/pages/index.module.css b/src/pages/index.module.css
@@ -43,9 +43,10 @@
 
 .tagline h2 {
   font-size: 2rem;
+  text-transform: capitalize;
 }
 
-.tagline h2 b {
+.tagline h2 span {
   color: var(--ifm-color-primary);
 }