Revise documentation for clarity and consistency

- Update tone guidelines to avoid using "please" in instructions
- Change titles and labels for consistency across documents
- Improve examples by replacing "❌" with "⛔" for clarity
- Enhance instructions and formatting in various templates

Author: hawkeyexl

AGENTS.md

@@ -155,13 +155,13 @@ All documentation must follow the [Google Developer Style Guide](https://develop
 **Voice and Tone:**
 - Write conversationally and friendly, like a knowledgeable friend, without being frivolous or overly colloquial
 - Avoid buzzwords, jargon, exclamation marks (except rare exciting moments), and phrases like "simply" or "it's easy"
-- Don't use "please" in instructions: ✅ "Click **View**" not ❌ "Please click **View**"
+- Don't use "please" in instructions: ✅ "Click **View**" not ⛔ "Please click **View**"
 
 **Language and Grammar:**
 - Use second person ("you") rather than first person ("we")
-- Use active voice: ✅ "Click the button" not ❌ "The button can be clicked"
-- Use present tense: ✅ "The API returns data" not ❌ "The API will return data"
-- Put conditions before instructions: ✅ "If you want to save, click **Save**" not ❌ "Click **Save** if you want to save"
+- Use active voice: ✅ "Click the button" not ⛔ "The button can be clicked"
+- Use present tense: ✅ "The API returns data" not ⛔ "The API will return data"
+- Put conditions before instructions: ✅ "If you want to save, click **Save**" not ⛔ "Click **Save** if you want to save"
 
 **Formatting:**
 - Use sentence case for headings (not Title Case)
@@ -173,8 +173,8 @@ All documentation must follow the [Google Developer Style Guide](https://develop
 
 **Examples of Tone:**
 - ✅ Good: "To get the user's phone number, call `user.phoneNumber.get`."
-- ❌ Too casual: "Dude! This API is totally awesome!"
-- ❌ Too formal: "The telephone number can be retrieved by the developer via the simple expedient of using the get method."
+- ⛔ Too casual: "Dude! This API is totally awesome!"
+- ⛔ Too formal: "The telephone number can be retrieved by the developer via the simple expedient of using the get method."
 
 ### The Good Docs Project Templates
 

docs/contributing/quick-start.mdx

@@ -1,11 +1,11 @@
 ---
-title: Quick Start
+title: Quick changes
 description: Make quick documentation fixes in 2-10 minutes using your browser.
-sidebar_label: Quick Start
+sidebar_label: Quick changes
 sidebar_position: 2
 ---
 
-# Quick contributions (2-10 minutes)
+# Quick changes (2-10 minutes)
 
 Fix typos, broken links, and small issues directly in your browser—no setup required.
 

docs/contributing/review-process.mdx

@@ -44,7 +44,7 @@ Before human review, automated checks verify your contribution.
 In your pull request, you'll see status checks:
 
 - ✅ **Green check**: Passed
-- ❌ **Red X**: Failed
+- ⛔ **Red X**: Failed
 - 🟡 **Yellow circle**: Running
 
 ### If checks fail
@@ -56,15 +56,15 @@ Don't panic! Failed checks are common and usually easy to fix.
 Vale checks writing style. Common issues:
 
 **"Use second person instead of first person"**
-- ❌ `We recommend using...`
+- ⛔ `We recommend using...`
 - ✅ `Use...` or `You can use...`
 
 **"Avoid using 'please' in instructions"**
-- ❌ `Please click the button`
+- ⛔ `Please click the button`
 - ✅ `Click the button`
 
 **"Use active voice"**
-- ❌ `The file can be uploaded by...`
+- ⛔ `The file can be uploaded by...`
 - ✅ `Upload the file by...`
 
 **Handling Vale suggestions:**
@@ -158,19 +158,19 @@ Does it match existing documentation?
 
 ### What reviewers DON'T block on
 
-#### ❌ Perfect prose
+#### ⛔ Perfect prose
 
 We value clear communication over elegant writing. If the meaning is clear, it's good enough.
 
-#### ❌ Comprehensive edge cases
+#### ⛔ Comprehensive edge cases
 
 Documentation doesn't need to cover every possible scenario. Focus on common use cases.
 
-#### ❌ Advanced formatting
+#### ⛔ Advanced formatting
 
 Basic formatting is sufficient. Fancy design elements are nice-to-have, not required.
 
-#### ❌ Minor style issues
+#### ⛔ Minor style issues
 
 If automated tools miss something minor, reviewers won't block on it. We fix small things during review.
 

docs/contributing/standard-contributions.mdx

@@ -1,11 +1,14 @@
 ---
-title: Standard Contributions
+title: Standard changes
 description: Add new content, examples, and improvements to Doc Detective documentation.
-sidebar_label: Standard Contributions
+sidebar_label: Standard changes
 sidebar_position: 3
 ---
 
-# Standard contributions (10-30 minutes)
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Standard changes (10-30 minutes)
 
 Add new content, examples, and improvements to the documentation. You can work in your browser or set up a local development environment.
 
@@ -14,7 +17,6 @@ Add new content, examples, and improvements to the documentation. You can work i
 - Adding missing steps to tutorials
 - Providing code examples
 - Adding troubleshooting tips
-- Creating FAQ entries
 - Adding "See also" links
 - Expanding brief explanations
 - Adding diagrams or screenshots
@@ -25,31 +27,35 @@ Add new content, examples, and improvements to the documentation. You can work i
 
 Use GitHub's web editor for smaller additions:
 
-1. Click "Edit this page" on any doc page
+1. Use the **Edit this page** button on any doc page
 2. Make your changes using the web editor
 3. Commit and create a pull request
 
-**Good for:** Adding a few paragraphs, code examples, or list items
+👉 See [Quick changes](quick-start) for detailed instructions.
+
+Good for adding a few paragraphs, code examples, or list items.
 
 ### Option 2: Local development (more powerful)
 
 Set up a local environment to preview changes as you write:
 
-👉 See [Local Development Setup](local-development) for detailed instructions
+👉 See [Local Development Setup](local-development) for detailed instructions.
 
-**Good for:** Adding multiple sections, working across multiple files, or seeing live previews
+Good for adding multiple sections, working across multiple files, or seeing live previews.
 
 ## Using content templates
 
 Templates help you structure your contribution and ensure you include all the important information.
 
 Choose the template that matches what you're creating:
 
-- **[How-to guide](templates/how-to)**: Task-focused step-by-step instructions
-- **[Tutorial](templates/tutorial)**: Learning-oriented guide through a complete workflow
-- **[Troubleshooting entry](templates/troubleshooting)**: Problem-solution format
-- **[Reference](templates/reference)**: Technical specifications or API documentation
-- **[Feature documentation](templates/feature)**: Document a new or changed feature
+| Template | Purpose |
+| --- | --- |
+| [How-to guide](templates/how-to) | Task-focused step-by-step instructions |
+| [Tutorial](templates/tutorial) | Learning-oriented guide through a complete workflow |
+| [Troubleshooting entry](templates/troubleshooting) | Problem-solution format |
+| [Reference](templates/reference) | Technical specifications or API documentation |
+| [Feature documentation](templates/feature) | Document a new or changed feature |
 
 ## Content guidelines
 
@@ -77,14 +83,16 @@ Related topics and next steps
 
 ### Write clear instructions
 
-✅ **Do:**
+✅ **Do**
+
 - Use second person ("you") and active voice
 - Start steps with action verbs: "Click", "Type", "Navigate"
 - Put conditions before instructions: "If you want to save, click **Save**"
 - Use numbered lists for sequential steps
 - Use bulleted lists for non-sequential items
 
-❌ **Don't:**
+⛔ **Don't**
+
 - Use first person ("we") or passive voice
 - Start steps with "Now" or "Then"
 - Bury conditions in the middle of instructions
@@ -111,7 +119,8 @@ Always test code examples before submitting:
 ```
 ````
 
-Include:
+Include
+
 - **Language identifier**: json, bash, typescript, etc.
 - **File name** (optional): Use `title="filename.ext"`
 - **Context**: Explain what the code does before showing it
@@ -124,30 +133,70 @@ Link to related documentation:
 See [Actions](/docs/category/actions) for available test actions.
 ```
 
-Use:
+Use
+
 - **Absolute paths** for internal links: `/docs/path/to/page`
 - **HTTPS** for external links: `https://example.com`
 - **Descriptive link text**: Not "click here" or "this link"
 
 ### Admonitions (callouts)
 
-Highlight important information:
-
-```markdown
-:::tip
-Doc Detective can automatically detect tests in your documentation!
-:::
-
-:::warning
-Make sure to close all browser instances before running tests.
-:::
-
-:::info
-You can use either JSON or YAML format for test specifications.
-:::
-```
-
-Available types: `note`, `tip`, `info`, `warning`, `danger`
+Highlight important information with admonitions. Make sure you use the appropriate type based on the severity and purpose of the message.
+
+<Tabs>
+  <TabItem label="Note" value="note">
+    ```markdown title="Note syntax"
+    :::note
+    `note` is for information that the user should be aware of but isn't critical.
+    :::
+    ```
+
+    :::note
+    `note` is for information that the user should be aware of but isn't critical.
+    :::
+  </TabItem>
+  <TabItem label="Tip" value="tip">
+    ```markdown title="Tip syntax"
+    :::tip
+    `tip` is for useful advice or shortcuts that can help the user.
+    :::
+    ```
+
+    :::tip
+    `tip` is for useful advice or shortcuts that can help the user.
+    :::
+  </TabItem>
+  <TabItem label="Info" value="info">
+    ```markdown title="Info syntax"
+    :::info
+    `info` is for useful information that isn't critical but may help the user.
+    :::
+    ```
+    :::info
+    `info` is for useful information that isn't critical but may help the user.
+    :::
+  </TabItem>
+  <TabItem label="Warning" value="warning">
+    ```markdown title="Warning syntax"
+    :::warning
+    `warning` should be used when an action may be difficult to undo or may cost the user unexpected time or resources.
+    :::
+    ```
+    :::warning
+    `warning` should be used when an action may be difficult to undo or may cost the user unexpected time or resources.
+    :::
+  </TabItem>
+  <TabItem label="Danger" value="danger">
+    ```markdown title="Danger syntax"
+    :::danger
+    `danger` should be used when there's a risk of data loss, unexpected cost, or harm.
+    :::
+    ```
+    :::danger
+    `danger` should be used when there's a risk of data loss, unexpected cost, or harm.
+    :::
+  </TabItem>
+</Tabs>
 
 ## Before submitting
 
@@ -169,39 +218,40 @@ Don't worry if you skip these—the CI/CD pipeline runs them automatically.
 
 Before creating a pull request:
 
-1. ✅ Read your changes out loud—does it make sense?
-2. ✅ Test any code examples or commands
-3. ✅ Check that links work
-4. ✅ Verify screenshots are clear and relevant
-5. ✅ Make sure formatting looks correct
+1. Read your changes out loud—does it make sense?
+2. Test any code examples or commands.
+3. Check that links work.
+4. Verify screenshots are clear and relevant.
+5. Make sure formatting looks correct.
 
 ### Create a pull request
 
-1. **Title**: Briefly describe what you added
+1. **Title**: Briefly describe what you added. Examples:
+
    - ✅ `Add troubleshooting guide for browser detection`
    - ✅ `Document file upload action with examples`
-   - ❌ `Update docs`
 
-2. **Description**: Use the PR template to provide context
+2. **Description**: Use the PR template to provide context:
+
    - What did you add or change?
    - Why is this helpful?
    - Related issue number (if applicable)
 
-3. **Submit**: Click "Create pull request"
+3. **Submit**: Create your pull request.
 
 ## What happens during review
 
 1. **Automated checks** run (typically 2-5 minutes)
 2. **Maintainer reviews** your contribution (within 5 business days)
 3. **Feedback or approval**:
-   - If changes are needed, update your pull request
+   - If changes are needed, update your pull request.
    - If approved, your contribution is merged!
 
 ### Understanding automated checks
 
 #### Vale (style checking)
 
-Vale enforces the Google Developer Style Guide. Common suggestions:
+Vale enforces the documentation style guide. Common suggestions include
 
 - Use "you" instead of "the user"
 - Avoid "please" in instructions
@@ -212,29 +262,32 @@ Most Vale suggestions are just that—suggestions. Reviewers use judgment.
 
 #### Link validation
 
-Checks that all links work. If this fails:
+Checks that all links work. If this fails,
+
 - Verify external URLs are correct
 - Check internal link paths (case-sensitive)
 - Make sure linked pages exist
 
 #### Build check
 
-Ensures the documentation site builds successfully. Failures usually indicate:
+Make sure that the documentation site builds successfully. Failures usually indicate
+
 - Markdown syntax errors
 - Missing closing tags
 - Invalid front matter
 
 ## Need help?
 
 ### During writing
-- **Not sure about structure?** Check similar pages in the docs
-- **Questions about content?** Ask in [Discord](https://discord.gg/2M7wXEThfF)
-- **Stuck on technical details?** Reference the [AGENTS.md](https://github.com/doc-detective/doc-detective.github.io/blob/main/AGENTS.md) file
+
+- **Not sure about structure?** Check similar pages in the docs.
+- **Questions about content or technical details?** Ask in [Discord](https://discord.gg/2M7wXEThfF).
 
 ### After submitting
-- **Automated checks failed?** Check the details in the PR—reviewers can help
-- **No response yet?** Wait 5 business days, then ping in the PR
-- **Need to make changes?** Just commit to the same branch—the PR updates automatically
+
+- **Automated checks failed?** Check the details in the PR—reviewers can help.
+- **No response yet?** Wait 5 business days, then ping in the PR.
+- **Need to make changes?** Just commit to the same branch—the PR updates automatically.
 
 ## Ready for bigger projects?
 

docs/contributing/substantial-contributions.mdx

@@ -1,11 +1,11 @@
 ---
-title: Substantial Contributions
+title: Substantial changes
 description: Take on major documentation projects with guidance and technical writer support.
-sidebar_label: Substantial Contributions
+sidebar_label: Substantial changes
 sidebar_position: 4
 ---
 
-# Substantial contributions (30+ minutes)
+# Substantial changes (30+ minutes)
 
 Major documentation projects that significantly expand or improve the Doc Detective documentation.