Skip to content

[task] Create troubleshooting documentation structure #2973

@github-actions

Description

@github-actions

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

  1. Create directory: docs/src/content/docs/troubleshooting/
  2. Create three foundational files:
    • errors.md - Common error messages and solutions
    • common-issues.md - Frequently encountered issues
    • validation-timing.md - When errors occur (schema vs compile vs runtime)
  3. Follow Astro Starlight format with proper frontmatter
  4. Use Diátaxis framework (this is reference documentation)

Files to Create

  • docs/src/content/docs/troubleshooting/errors.md
  • docs/src/content/docs/troubleshooting/common-issues.md
  • docs/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

AI generated by Plan Command for discussion #2969

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions