Skip to content

[task] Create troubleshooting documentation structure #2973

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions