Create comprehensive real-world examples guide for common documentation testing scenarios

[hawkeyexl]

Create a new documentation page that provides complete, copy-paste-ready examples for common documentation testing scenarios. This guide should help new users quickly find a relevant example, understand it, and adapt it to their needs.
Context
New users learn best from complete working examples they can adapt. Currently, Doc Detective has a basic "Create Your First Test" guide, but users need more diverse, real-world scenarios that map to their actual documentation testing needs. This is the highest priority documentation gap for new user adoption.
Target Audience
Technical writers new to documentation testing
Developers documenting their products
QA professionals exploring docs-as-tests approach
Anyone looking to validate documentation accuracy
User Stories
"As a technical writer, I want to test my CLI installation guide so that I know the commands actually work"
"As a developer, I want to test my REST API tutorial so that the examples stay current with the API"
"As a docs manager, I want to validate screenshots in my UI walkthrough so they don't go stale"
"As a support engineer, I want to test our troubleshooting procedures so they help customers effectively"
Content Structure
Create a new page at /docs/get-started/real-world-examples.md with the following sections:
Introduction (100-150 words)
Explain the purpose: complete, working examples for common scenarios
Set expectations: each example is copy-paste ready
Provide navigation: link to specific use cases below
Use Case Template (repeat for each scenario)
For each use case, include:
Scenario Title (e.g., "Testing a CLI Installation Guide")
When to use this (1-2 sentences describing the scenario)
What this example does (2-3 bullet points)
Prerequisites (what users need before starting)
Complete working example (full test specification with inline comments)
Expected output (what success looks like)
Common variations (2-3 ways to adapt the example)
Next steps (links to relevant advanced topics)
Required Use Cases

1. Testing a CLI Installation Guide
   Context: Command-line tools are fundamental to developer documentation. Installation guides must have accurate commands that work across different operating systems. Testing these ensures users can actually install your tool.
   Example should include:
   Using runShell action to execute installation commands
   Checking command exit codes
   Validating installed version
   Testing basic functionality post-install
   Handling platform-specific variations
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Install the CLI tool using npm",
   "runShell": {
   "command": "npm install -g your-cli-tool",
   "stdio": ""
   }
   },
   {
   "description": "Verify installation by checking version",
   "runShell": {
   "command": "your-cli-tool --version",
   "stdio": "v1.2.3"
   }
   },
   {
   "description": "Test basic functionality",
   "runShell": {
   "command": "your-cli-tool hello",
   "stdio": "Hello, World!"
   }
   }
   ]
   }
   ]
   }
2. Testing a REST API Tutorial
   Context: API documentation often includes curl commands or code examples that demonstrate endpoint usage. These examples must stay synchronized with the actual API behavior, including request/response formats and status codes.
   Example should include:
   Multiple API calls in sequence (create, read, update patterns)
   Request body validation
   Response body validation
   Status code checking
   Using variables to chain API calls (e.g., using ID from create in subsequent calls)
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Create a new user",
   "httpRequest": {
   "url": "https://api.example.com/users",
   "method": "POST",
   "request": {
   "body": {
   "name": "Test User",
   "email": "test@example.com"
   }
   },
   "response": {
   "body": {
   "id": "string",
   "name": "Test User",
   "email": "test@example.com"
   }
   },
   "statusCodes": [201]
   },
   "variables": {
   "USER_ID": "$$response.body.id"
   }
   },
   {
   "description": "Retrieve the created user",
   "httpRequest": {
   "url": "https://api.example.com/users/$USER_ID",
   "method": "GET",
   "response": {
   "body": {
   "id": "$USER_ID",
   "name": "Test User"
   }
   },
   "statusCodes": [200]
   }
   }
   ]
   }
   ]
   }
3. Validating Screenshots in a UI Walkthrough
   Context: UI documentation often includes screenshots to help users visually confirm they're in the right place. Screenshots go stale when UIs change. Automated screenshot capture and comparison ensures visual documentation stays current.
   Example should include:
   Navigation to specific pages
   Finding specific UI elements to confirm correct page
   Taking screenshots
   Visual comparison with previous screenshots
   Handling minor acceptable variations
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Navigate to the dashboard",
   "goTo": "https://app.example.com/dashboard"
   },
   {
   "description": "Wait for page to fully load",
   "find": {
   "selector": ".dashboard-loaded",
   "timeout": 10000
   }
   },
   {
   "description": "Capture dashboard screenshot",
   "screenshot": {
   "path": "screenshots/dashboard.png",
   "maxVariation": 0.05,
   "overwrite": "aboveVariation"
   }
   },
   {
   "description": "Navigate to settings page",
   "click": "Settings"
   },
   {
   "description": "Capture settings screenshot",
   "screenshot": {
   "path": "screenshots/settings.png",
   "maxVariation": 0.05,
   "overwrite": "aboveVariation"
   }
   }
   ]
   }
   ]
   }
4. Testing a Multi-Step User Workflow
   Context: Documentation often describes complete workflows that span multiple pages or interactions. Testing these end-to-end ensures each step still works and properly leads to the next step.
   Example should include:
   Navigation through multiple pages
   Form filling
   Button clicking
   Validation of success messages
   Screenshot capture at key points
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Navigate to registration page",
   "goTo": "https://example.com/register"
   },
   {
   "description": "Fill in username",
   "find": {
   "selector": "#username",
   "click": true,
   "type": "testuser123"
   }
   },
   {
   "description": "Fill in email",
   "find": {
   "selector": "#email",
   "click": true,
   "type": "test@example.com"
   }
   },
   {
   "description": "Fill in password",
   "find": {
   "selector": "#password",
   "click": true,
   "type": "SecurePass123!"
   }
   },
   {
   "description": "Submit registration form",
   "click": "Create Account"
   },
   {
   "description": "Verify success message",
   "find": "Account created successfully"
   },
   {
   "description": "Capture confirmation page",
   "screenshot": "registration-success.png"
   }
   ]
   }
   ]
   }
5. Testing Code Examples with Multiple Languages
   Context: SDK documentation often provides code examples in multiple programming languages. Each language's examples must be syntactically correct and produce expected results.
   Example should include:
   Using runCode action for multiple languages
   Validating output from code execution
   Handling language-specific dependencies
   Testing both successful execution and expected output
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Test Python example",
   "runCode": {
   "language": "python",
   "code": [
   "import requests",
   "response = requests.get('https://api.example.com/status')",
   "print(response.json()['status'])"
   ],
   "stdio": "healthy"
   }
   },
   {
   "description": "Test JavaScript example",
   "runCode": {
   "language": "javascript",
   "code": [
   "const response = await fetch('https://api.example.com/status');",
   "const data = await response.json();",
   "console.log(data.status);"
   ],
   "stdio": "healthy"
   }
   }
   ]
   }
   ]
   }
6. Testing Documentation Links
   Context: Documentation contains many links to other pages, external resources, or API endpoints. Broken links frustrate users and damage credibility. Link checking ensures all references remain valid.
   Example should include:
   Using checkLink for multiple URLs
   Handling both internal and external links
   Accepting multiple valid status codes
   Organizing link tests efficiently
   {
   "tests": [
   {
   "steps": [
   {
   "description": "Check main documentation links",
   "checkLink": "https://docs.example.com/getting-started"
   },
   {
   "description": "Check API reference",
   "checkLink": {
   "url": "https://api.example.com/v1/docs",
   "statusCodes": [200, 301, 302]
   }
   },
   {
   "description": "Check external resource",
   "checkLink": "https://github.com/example/repo"
   }
   ]
   }
   ]
   }
   Implementation Guidelines
   File Location
   Create at: docs/get-started/real-world-examples.md
   Add to sidebar navigation after "Create Your First Test"
   Writing Style
   Use humble yet confident tone (avoid "just" or "simply")
   Focus on the user's perspective, not first-person
   Include concrete, specific examples
   Explain why each step matters, not just what it does
   Code Comments
   Add inline comments to test specifications explaining key concepts
   Highlight important configuration options
   Note common mistakes to avoid
   Cross-Linking
   Link to relevant action references (e.g., /docs/get-started/actions/httpRequest)
   Link to setup guides for prerequisites
   Link to troubleshooting when mentioning potential issues
   Connect to advanced topics users might explore next
   Validation
   Each example must:
   Be tested and confirmed working
   Include complete configuration (no missing pieces)
   Provide actual output examples
   Note any environment-specific requirements
   Success Criteria
   [ ] Page created with all 6 use cases
   [ ] Each example is complete and copy-paste ready
   [ ] All examples have been tested and work as documented
   [ ] Common variations section for each use case
   [ ] Cross-links to relevant documentation pages
   [ ] Added to sidebar navigation
   [ ] Includes troubleshooting tips for each scenario
   [ ] Mobile-responsive code blocks
   [ ] Accessible to screen readers
   Related Issues
   This addresses the Get started #1 priority documentation gap
   Supports user onboarding improvements
   Reduces time-to-first-success for new users
   Additional Resources
   Current getting started guide: /docs/get-started/create-your-first-test.md
   Action references: /docs/category/actions
   Schema references: /docs/category/schemas