Add comprehensive real-world examples guide for common documentation testing scenarios #96
Conversation
|
|
|
Important Review skippedBot user detected. To trigger a single review, invoke the You can disable this status message by setting the Comment |
Co-authored-by: hawkeyexl <[email protected]>
PR Change SummaryCreated a comprehensive guide for real-world documentation testing scenarios to enhance user understanding and adoption.
Added Files
How can I customize these reviews?Check out the Hyperlint AI Reviewer docs for more information on how to customize the review. If you just want to ignore it on this PR, you can add the Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add |
1 similar comment
PR Change SummaryCreated a comprehensive guide for real-world documentation testing scenarios to enhance user understanding and adoption.
Added Files
How can I customize these reviews?Check out the Hyperlint AI Reviewer docs for more information on how to customize the review. If you just want to ignore it on this PR, you can add the Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add |
|
@copilot Break the large file into individual pages per month example. |
Co-authored-by: hawkeyexl <[email protected]>
Split the large file into individual pages per use case in commit 94036ca. The real-world examples guide is now organized as a category with 7 separate pages:
This structure improves navigation and maintainability, with each example in its own file.
|
Overview
This PR adds a new comprehensive guide that provides complete, copy-paste-ready examples for 6 common documentation testing scenarios. The guide addresses the highest priority documentation gap for new user adoption by helping users quickly find relevant examples, understand them, and adapt them to their needs.
What's New
Created
/docs/get-started/real-world-examples/as a category with 7 separate pages:Structure
The guide is organized as an expandable sidebar category with individual pages for each use case, improving navigation and maintainability. Each scenario follows a consistent, user-focused template:
Documentation Standards
Navigation
The guide is positioned in the sidebar between "Create your first test" and "Explore sample tests" as an expandable category, providing a natural progression for new users:
Screenshots
Overview Page with Sidebar Navigation
The overview page provides an introduction to all available scenarios with links to each individual page. The sidebar shows "Real-world examples" as an expandable category, making it easy for users to navigate directly to specific examples.
Benefits
Impact
This guide directly addresses user stories from the issue:
By providing immediately usable examples in an easily navigable structure, this reduces time-to-first-success for new users and accelerates Doc Detective adoption.
Related
Closes #95
Original prompt
This section details on the original issue you should resolve
<issue_title>Create comprehensive real-world examples guide for common documentation testing scenarios</issue_title>
<issue_description>
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
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!"
}
}
]
}
]
}
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": "[email protected]"
}
},
"response": {
"body": {
"id": "string",
"name": "Test User",
"email": "[email protected]"
}
},
"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]
}
}
]
}
]
}
Context: UI d...
Fixes #95
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.