Fix Vale false positive with markup and restore alex.Condescending to error

Copilot · hawkeyexl · Copilot · commit 2d289c3cb672 · 2025-10-10T21:07:27.000Z
Co-authored-by: hawkeyexl &lt;5209367+hawkeyexl@users.noreply.github.com&gt;
diff --git a/.vale.ini b/.vale.ini
@@ -22,8 +22,3 @@ Google.Quotes = warning
 # Vale.Spelling doesn't respect vocabulary in frontmatter/titles
 # Relax to warning for technical docs with API terms
 Vale.Spelling = warning
-
-# alex.Condescending flags words like "simple" and "easy" which in technical
-# documentation often describe the example's complexity, not the reader's ability
-# Relax to warning so reviewers can use judgment
-alex.Condescending = warning
diff --git a/docs/contributing/quick-start.mdx b/docs/contributing/quick-start.mdx
@@ -80,7 +80,7 @@ For quick fixes like typos and link updates, no testing is required. The automat
 
 ### What if the automated checks fail?
 
-Don't worry. The reviewer will help you fix any issues. Most common failures are easily correctable:
+Don't worry. The reviewer will help you fix any issues. Most common failures are correctable:
 - __Vale failures__: Usually suggest alternative wording (often just suggestions)
 - __Link check failures__: Means a link is broken or inaccessible
 - __Build failures__: Usually means there's a syntax error in Markdown
diff --git a/docs/contributing/review-process.mdx b/docs/contributing/review-process.mdx
@@ -50,7 +50,7 @@ In your pull request, you'll see status checks:
 
 ### If checks fail
 
-Don't panic. Failed checks are common and usually easy to fix.
+Don't panic. Failed checks are common and can usually be fixed.
 
 #### Vale failures
 
diff --git a/docs/contributing/templates/feature.mdx b/docs/contributing/templates/feature.mdx
@@ -219,7 +219,7 @@ Examples should be copy-pasteable and work as-is:
 }
 ```
 
-### Document breaking changes clearly
+### Document breaking changes
 
 Be explicit about what breaks:
 
@@ -373,7 +373,7 @@ None. This is a backward-compatible addition. Existing screenshots continue to w
 
 ## Checklist before submitting
 
-- [ ] Clearly explains what the feature is and why it matters
+- [ ] Explains what the feature is and why it matters
 - [ ] Provides complete, working examples
 - [ ] Documents all configuration options
 - [ ] Includes migration guide if replacing existing functionality
diff --git a/docs/contributing/templates/troubleshooting.mdx b/docs/contributing/templates/troubleshooting.mdx
@@ -368,7 +368,7 @@ If you've tried these solutions and still have issues:
 
 ## Checklist before submitting
 
-- [ ] Problem is clearly stated in the title
+- [ ] Problem is stated in the title
 - [ ] Symptoms are specific and observable
 - [ ] Exact error messages are included
 - [ ] Root cause is explained
diff --git a/docs/contributing/templates/tutorial.mdx b/docs/contributing/templates/tutorial.mdx
@@ -148,14 +148,14 @@ Each step should build on previous ones:
 
 ✅ Good progression:
 
-1. Create a simple test with one action
+1. Create a basic test with one action
 2. Add a second action to create a flow
 3. Add error handling
 4. Organize into a test suite
 
 ⛔ Poor progression:
 
-1. Create a simple test
+1. Create a basic test
 2. Deploy to production (too big a jump)
 
 ### Explain the why
@@ -431,7 +431,7 @@ Now that you understand the basics:
 
 ## Checklist before submitting
 
-- [ ] Clearly states what users will learn
+- [ ] States what users will learn
 - [ ] Lists what users will build
 - [ ] Prerequisites and time estimate included
 - [ ] Steps build progressively
diff --git a/docs/contributing/testing.mdx b/docs/contributing/testing.mdx
@@ -407,7 +407,7 @@ npx doc-detective runTests --input your-test.spec.json --logLevel debug
 
 ## Test best practices
 
-### Keep tests simple
+### Keep tests straightforward
 
 ✅ **Do:**
 - Test one concept per test
@@ -424,7 +424,7 @@ npx doc-detective runTests --input your-test.spec.json --logLevel debug
 ### Make tests maintainable
 
 ✅ **Do:**
-- Use comments to explain non-obvious steps
+- Use comments to explain complex steps
 - Group related tests in the same file
 - Use descriptive action parameters
 - Clean up after tests (delete files, etc.)
diff --git a/docs/get-started/actions/find.mdx b/docs/get-started/actions/find.mdx
@@ -16,7 +16,7 @@ The `find` action locates an element in the current interface based on its displ
 
 If multiple elements match the specified criteria (`elementText` and/or `selector`), the step operates on the first matched element. Ensure your criteria uniquely identify the target element.
 
-You can specify the target element directly using a string (for simple text or selector lookup) or use an object for more detailed options and interactions:
+You can specify the target element directly using a string (for basic text or selector lookup) or use an object for more detailed options and interactions:
 
 - **String Shorthand:** Provide the display text or CSS/XPath selector directly as the value for the `find` key. If elements are found by both text and selector, the element found by matching text is used.
   - Example: `"find": "Login"` or `"find": "#username"`.
diff --git a/docs/get-started/actions/httpRequest.mdx b/docs/get-started/actions/httpRequest.mdx
@@ -14,9 +14,9 @@ import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 
 The `httpRequest` action makes arbitrary HTTP calls, allowing you to interact with and validate APIs or other web services directly within your tests.
 
-You can specify a simple GET request using a string shorthand or use an object for more complex requests and validation:
+You can specify a basic GET request using a string shorthand or use an object for more complex requests and validation:
 
-- **String Shorthand:** Provide the full URL directly as the value for the `httpRequest` key. This performs a simple GET request to that URL.
+- **String Shorthand:** Provide the full URL directly as the value for the `httpRequest` key. This performs a basic GET request to that URL.
 - **Object Format:** Use an object with the following properties:
   - `url`: (Required unless using `openApi`) The target URL for the request.
   - `method`: (Optional) The HTTP method (for example, `GET`, `POST`, `PUT`, `DELETE`). Defaults to `GET`.
@@ -46,15 +46,15 @@ You can specify a simple GET request using a string shorthand or use an object f
 
 Here are a few ways you might use the `httpRequest` action:
 
-### Simple GET request (string shorthand)
+### Basic GET request (string shorthand)
 
 ```json
 {
   "tests": [
     {
       "steps": [
         {
-          "description": "Perform a simple GET request.",
+          "description": "Perform a basic GET request.",
           "httpRequest": "https://reqres.in/api/users?page=2"
         }
       ]
diff --git a/docs/get-started/actions/record.mdx b/docs/get-started/actions/record.mdx
@@ -33,7 +33,7 @@ You can specify the recording action in several ways:
 
 Here are a few ways you might use the `record` and `stopRecord` actions:
 
-### Simple recording (boolean shorthand)
+### Basic recording (boolean shorthand)
 
 Starts recording to a default path like `output/record_1745032062266.mp4` and stops later.
 
diff --git a/docs/get-started/actions/runCode.mdx b/docs/get-started/actions/runCode.mdx
@@ -38,7 +38,7 @@ You must specify the `runCode` action using an object format with the following
 
 Here are a few ways you might use the `runCode` action:
 
-### Run a simple Python script
+### Run a basic Python script
 
 This example prints "hello world" using Python.
 
@@ -48,7 +48,7 @@ This example prints "hello world" using Python.
     {
       "steps": [
         {
-          "description": "Run a simple Python script.",
+          "description": "Run a basic Python script.",
           "runCode": {
             "language": "python",
             "code": "print('hello world')"
diff --git a/docs/get-started/actions/runShell.mdx b/docs/get-started/actions/runShell.mdx
@@ -36,7 +36,7 @@ You can specify the command directly as a string or use an object for more optio
 
 Here are a few ways you might use the `runShell` action:
 
-### Run a simple command (string shorthand)
+### Run a basic command (string shorthand)
 
 This example prints "hello world" to the output.
 
@@ -46,7 +46,7 @@ This example prints "hello world" to the output.
     {
       "steps": [
         {
-          "description": "Run a simple command.",
+          "description": "Run a basic command.",
           "runShell": "echo 'hello world'"
         }
       ]
diff --git a/docs/get-started/actions/screenshot.mdx b/docs/get-started/actions/screenshot.mdx
@@ -39,7 +39,7 @@ You can specify the screenshot action in several ways:
 
 Here are a few ways you might use the `screenshot` action:
 
-### Simple full viewport screenshot (boolean shorthand)
+### Basic full viewport screenshot (boolean shorthand)
 
 Saves to a default path like `output/screenshot_1745032062266.png`.
 
@@ -49,7 +49,7 @@ Saves to a default path like `output/screenshot_1745032062266.png`.
     {
       "steps": [
         {
-          "description": "Take a simple screenshot.",
+          "description": "Take a basic screenshot.",
           "screenshot": true
         }
       ]
diff --git a/docs/get-started/actions/stopRecord.mdx b/docs/get-started/actions/stopRecord.mdx
@@ -14,7 +14,7 @@ import JSONSchemaViewer from "@theme/JSONSchemaViewer";
 
 The `stopRecord` action stops a video recording previously started by a [`record`](record) action and saves the video file.
 
-This action takes a simple boolean value:
+This action takes a boolean value:
 
 - `stopRecord: true`: Stops the current recording.
 
diff --git a/docs/get-started/actions/type.mdx b/docs/get-started/actions/type.mdx
@@ -16,7 +16,7 @@ The `type` action simulates key presses, including special keys such as Enter. T
 
 You can specify the keys to type in several ways:
 
-- **String Shorthand:** Provide a simple string as the value for the `type` key.
+- **String Shorthand:** Provide a string as the value for the `type` key.
 - **Array Shorthand:** Provide an array of strings. Each string in the array is typed sequentially. This allows mixing regular text with [special keys](#special-keys).
 - **Object Format:** Use an object for more control:
   - `keys`: (Required) A string or an array of strings representing the keys to type.
diff --git a/docs/get-started/config/contexts/index.md b/docs/get-started/config/contexts/index.md
@@ -207,7 +207,7 @@ This context targets Windows or Linux:
 
 ## Examples
 
-### Simple Contexts
+### Basic Contexts
 
 - Run tests in Chrome on all supported platforms:
 
diff --git a/docs/get-started/selectors/css.mdx b/docs/get-started/selectors/css.mdx
@@ -13,7 +13,7 @@ Use CSS selectors in Doc Detective actions like [`find`](/docs/get-started/actio
 
 - You need to target elements by their attributes, classes, or IDs
 - You want a selector that's more reasonable to read and maintain
-- The element doesn't have easily identifiable display text
+- The element doesn't have identifiable display text
 
 ## Basic CSS selector patterns
 
@@ -241,7 +241,7 @@ Work with your engineering team to add `data-testid` or similar attributes to im
 
 ### Avoid fragile selectors
 
-Selectors that are too specific can break easily when the page structure changes:
+Selectors that are too specific can break when the page structure changes:
 
 :::warning[Fragile]
 `div > div > div > span.text`
diff --git a/docs/get-started/selectors/xpath.mdx b/docs/get-started/selectors/xpath.mdx
@@ -32,7 +32,7 @@ XPath selectors in Doc Detective must start with `//` or `/` to be recognized as
   ```
   
   :::warning[Avoid absolute paths]
-  They're fragile and break easily when the page structure changes.
+  They're fragile and break when the page structure changes.
   :::
 
 - **Relative path:** Starts with `//` and finds elements anywhere in the document
diff --git a/docs/get-started/tests/index.mdx b/docs/get-started/tests/index.mdx
@@ -440,7 +440,7 @@ To add detected test functionality to HTML or AsciiDoc files, you would need to
 
 ### Default actions
 
-If you only need to perform simple steps, you can define actions using a shorthand of only specifying the action name. Doc Detective uses default actions, substituting the first capture group (or if there are no capture groups, the entire match) from the regex pattern into the most common location for the action. In the above example, the config generates a `goTo` action for every Markdown hyperlink preceded by a navigation verb.
+If you only need to perform basic steps, you can define actions using a shorthand of only specifying the action name. Doc Detective uses default actions, substituting the first capture group (or if there are no capture groups, the entire match) from the regex pattern into the most common location for the action. In the above example, the config generates a `goTo` action for every Markdown hyperlink preceded by a navigation verb.
 
 The default actions are as follows:
 
diff --git a/docs/get-started/tutorials/set-up-your-test-environment.mdx b/docs/get-started/tutorials/set-up-your-test-environment.mdx
@@ -19,7 +19,7 @@ You can use Doc Detective directly against your production site. For testing, it
    Replace `<path-to-expanded-test-examples>` with the actual path where you expanded the `TestExamples.zip` file.
 1. Install and run a webserver. Running your tests against a local server allows you to make edits and see them in real time. Also, you need to serve the files in a web browser to experiment with video recording and other features.
 
-   Any web server will do, but here are a few easy options (unassociated with Doc Detective):
+   Any web server will do, but here are a few options (unassociated with Doc Detective):
 
    <Tabs>
       <TabItem value='python' label='Python'>
@@ -37,8 +37,12 @@ You can use Doc Detective directly against your production site. For testing, it
          ```
       </TabItem>
       <TabItem value='vscode' label='VSCode'>
+         <!-- vale off -->
+
          In VSCode, search for and install the [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) extension. It gives you a local development server with live reload capability.
 
+         <!-- vale on -->
+
          :::info
          You need to set the port number to `8080` in your VSCode settings to match the Doc Detective tutorials.
          :::

Original file line number	Diff line number	Diff line change
`@@ -14,9 +14,9 @@ import JSONSchemaViewer from "@theme/JSONSchemaViewer";`
`14`	`14`
`15`	`15`	The `httpRequest` action makes arbitrary HTTP calls, allowing you to interact with and validate APIs or other web services directly within your tests.
`16`	`16`
`17`		`-You can specify a simple GET request using a string shorthand or use an object for more complex requests and validation:`
	`17`	`+You can specify a basic GET request using a string shorthand or use an object for more complex requests and validation:`
`18`	`18`
`19`		-- String Shorthand: Provide the full URL directly as the value for the `httpRequest` key. This performs a simple GET request to that URL.
	`19`	+- String Shorthand: Provide the full URL directly as the value for the `httpRequest` key. This performs a basic GET request to that URL.
`20`	`20`	`- Object Format: Use an object with the following properties:`
`21`	`21`	- `url`: (Required unless using `openApi`) The target URL for the request.
`22`	`22`	- `method`: (Optional) The HTTP method (for example, `GET`, `POST`, `PUT`, `DELETE`). Defaults to `GET`.
`@@ -46,15 +46,15 @@ You can specify a simple GET request using a string shorthand or use an object f`
`46`	`46`
`47`	`47`	Here are a few ways you might use the `httpRequest` action:
`48`	`48`
`49`		`-### Simple GET request (string shorthand)`
	`49`	`+### Basic GET request (string shorthand)`
`50`	`50`
`51`	`51`	```json
`52`	`52`	`{`
`53`	`53`	`"tests": [`
`54`	`54`	`{`
`55`	`55`	`"steps": [`
`56`	`56`	`{`
`57`		`- "description": "Perform a simple GET request.",`
	`57`	`+ "description": "Perform a basic GET request.",`
`58`	`58`	`"httpRequest": "https://reqres.in/api/users?page=2"`
`59`	`59`	`}`
`60`	`60`	`]`