Review documentation for clarity and precision (#117)

Copilot · hawkeyexl · web-flow · commit 521915152b1f · 2025-11-07T07:16:49.000-08:00
* Initial plan

* Improve documentation clarity per Google Developer Style Guide

Co-authored-by: hawkeyexl &lt;5209367+hawkeyexl@users.noreply.github.com&gt;

* Additional documentation clarity improvements

Co-authored-by: hawkeyexl &lt;5209367+hawkeyexl@users.noreply.github.com&gt;

---------

Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: hawkeyexl &lt;5209367+hawkeyexl@users.noreply.github.com&gt;
diff --git a/docs/get-started/actions/click.mdx b/docs/get-started/actions/click.mdx
@@ -21,7 +21,7 @@ The `click` action works in several ways:
 
 If you need to find an element before clicking it, consider using the [`find`](/docs/get-started/actions/find) action, which lets you locate elements and optionally click them in a single step.
 
-**Note:** If you use the `click` action without specifying a target (using element text or selector), it will click the active element or the element at the current cursor position.
+**Note:** If you use the `click` action without specifying a target (using element text or selector), it clicks the active element or the element at the current cursor position.
 
 ## Properties
 
diff --git a/docs/get-started/concepts.md b/docs/get-started/concepts.md
@@ -20,7 +20,7 @@ A step is a portion of a test that includes a single action. Conceptually parall
 
 ## Action
 
-An action is the task performed in a step. Doc Detective supports a variety of actions:
+An action performs a task in a step. Doc Detective supports a variety of actions:
 
 | Name                                                        | Description                                                                                                                                               |
 | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -34,8 +34,8 @@ An action is the task performed in a step. Doc Detective supports a variety of a
 | [loadVariables](/docs/get-started/actions/loadVariables) | Load environment variables from a `.env` file.                                                                                                            |
 | [saveCookie](/docs/get-started/actions/saveCookie)       | Save a specific browser cookie to a file or environment variable for later reuse.                                                                         |
 | [loadCookie](/docs/get-started/actions/loadCookie)       | Load a specific cookie from a file or environment variable into the browser.                                                                              |
-| [record](/docs/get-started/actions/record)               | Capture a video of test run.                                                                                                                              |
-| [stopRecord](/docs/get-started/actions/stopRecord)       | Stop capturing a video of test run.                                                                                                                       |
+| [record](/docs/get-started/actions/record)               | Capture a video of the test run.                                                                                                                              |
+| [stopRecord](/docs/get-started/actions/stopRecord)       | Stop capturing a video of the test run.                                                                                                                       |
 | [type](/docs/get-started/actions/type)                   | Type keys. To type special keys, begin and end the string with `$` and use the special key’s enum. For example, to type the Escape key, enter `$ESCAPE$`. |
 | [wait](/docs/get-started/actions/wait)                   | Pause before performing the next action.                                                                                                                  |
 
diff --git a/docs/get-started/create-your-first-test.mdx b/docs/get-started/create-your-first-test.mdx
@@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';
 
 # Create your first test
 
-In this tutorial, you will create a basic test that navigates to a webpage, validates the presence of specific elements, and captures a screenshot. This will introduce you to fundamental Doc Detective actions that are essential for creating more advanced tests in the future.
+In this tutorial, you create a basic test that navigates to a webpage, validates the presence of specific elements, and captures a screenshot. This tutorial introduces you to fundamental Doc Detective actions that are essential for creating more advanced tests.
 
 ## What is a test?
 
diff --git a/docs/get-started/intro.mdx b/docs/get-started/intro.mdx
@@ -68,14 +68,14 @@ Doc Detective doesn’t scan your code or generate documentation. It verifies th
 
 ### Write your code
 
-While Doc Detective can write tests from scanning your documentation, it can’t write code for you. Sorry.
+Doc Detective can't write code for you.
 
 ## Who is Doc Detective for?
 
 As an open source and accessible project, Doc Detective is for anyone who's interested. More specifically, here are some groups who could benefit:
 
 - **Small teams:** There’s often limited personnel or budget dedicated to a project, and documentation often gets deprioritized as a result. With Doc Detective, you can spend less time reviewing published documentation and trust that it's still functional and accurate for the end user.
-- **Large teams:** The more people you have contributing to a project, the faster it can change shape. In cases where development is outpacing documentation, Doc Detective keeps a watchful eye on the changes made and note any inconsistencies.
+- **Large teams:** The more people you have contributing to a project, the faster it can change shape. In cases where development is outpacing documentation, Doc Detective keeps a watchful eye on the changes made and notes any inconsistencies.
 - **Anything in between:** You can be a team of one or of one thousand and still find a use for Doc Detective. When it comes time to address the documentation of your project, look to Doc Detective to ease the burden and help bring consistency and accuracy to the end user.
 
 ## Next steps
diff --git a/docs/get-started/sample-tests.mdx b/docs/get-started/sample-tests.mdx
@@ -57,7 +57,7 @@ docker run -v .:/app docdetective/docdetective --input /app/doc-content-inline-t
   </TabItem>
 </Tabs>
 
-If you have test files in multiple directories or want to specify multiple files, then enter them separated with commas:
+If you have test files in multiple directories or want to specify multiple files, enter them separated with commas:
 
 <Tabs>
   <TabItem value="npx" label="NPX" default>
@@ -76,7 +76,7 @@ docker run -v .:/app docdetective/docdetective --input /app/doc-content-inline-t
   </TabItem>
 </Tabs>
 
-To customize your test, file type, and directory options, create a `.doc-detective.json` [config](/docs/references/schemas/config) file. If a `.doc-detective.json` file exists in the directory when you run the comment, Doc Detective loads the config. Otherwise, you can specify a config path with the `--config` argument.
+To customize your test, file type, and directory options, create a `.doc-detective.json` [config](/docs/references/schemas/config) file. If a `.doc-detective.json` file exists in the directory when you run the command, Doc Detective loads the config. Otherwise, you can specify a config path with the `--config` argument.
 
 <Tabs>
   <TabItem value="npx" label="NPX" default>
diff --git a/docs/get-started/selectors/xpath.mdx b/docs/get-started/selectors/xpath.mdx
@@ -574,7 +574,7 @@ $x("//button[contains(text(), 'Submit')]")[0].click()
 1. Open Developer Tools (F12)
 2. Go to the Console tab
 3. Type `$x("your-xpath-here")` and press Enter
-4. The console will show all matching elements
+4. The console shows all matching elements
 5. Hover over results to highlight them on the page
 
 ### Common issues
diff --git a/docs/get-started/tutorials/set-up-your-test-environment.mdx b/docs/get-started/tutorials/set-up-your-test-environment.mdx
@@ -44,7 +44,7 @@ You can use Doc Detective directly against your production site. For testing, it
          {/* vale on */}
 
          :::info
-         You need to set the port number to `8080` in your VSCode settings to match the Doc Detective tutorials.
+         To match the Doc Detective tutorials, set the port number to `8080` in your VSCode settings.
          :::
       </TabItem>
    </Tabs>
