-
Notifications
You must be signed in to change notification settings - Fork 36
Closed
Labels
Description
Objective
Create the docs/src/content/docs/troubleshooting/ directory structure with foundational troubleshooting documentation files.
Context
This addresses Issue #3 from discussion #2969. The codebase contains 328 error messages but has zero documentation for them. Users encountering errors cannot search documentation for solutions or understand error context.
Approach
- Create directory:
docs/src/content/docs/troubleshooting/ - Create three foundational files:
errors.md- Common error messages and solutionscommon-issues.md- Frequently encountered issuesvalidation-timing.md- When errors occur (schema vs compile vs runtime)
- Follow Astro Starlight format with proper frontmatter
- Use Diátaxis framework (this is reference documentation)
Files to Create
docs/src/content/docs/troubleshooting/errors.mddocs/src/content/docs/troubleshooting/common-issues.mddocs/src/content/docs/troubleshooting/validation-timing.md
Structure for errors.md
Include sections for:
- Schema validation errors
- Compile-time errors
- Runtime errors
- Each error should include: description, cause, solution, example
Acceptance Criteria
- Directory
docs/src/content/docs/troubleshooting/exists - All three markdown files created with proper frontmatter
- Files follow Astro Starlight and Diátaxis guidelines
- Navigation updated to include troubleshooting section
- Documentation builds successfully with
npm run build
Related to [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969
AI generated by Plan Command for discussion #2969
Copilot