Documentation•Reference

Docs Quality and LLM Readiness

Use this guide to keep HazelJS docs reliable for both human readers and LLM-based tooling.

Why this matters

LLMs are very sensitive to inconsistent examples, stale versions, and conflicting command names. A single incorrect snippet can reduce answer quality across many downstream tools.

Source of truth

Treat these as canonical, in this order:

  1. Package source code in hazeljs/packages/*
  2. Human docs in src/content/docs/**
  3. Machine-readable metadata in public/api/*.json

If (2) or (3) diverges from (1), fix docs/metadata immediately.

Authoring rules

  • Use one CLI command style everywhere: hazel ...
  • Avoid hardcoded old version claims (for example "should display v0.2.0")
  • Prefer version-agnostic wording for fast-moving CLI output
  • Keep import snippets executable and lint-friendly
  • Keep package names exact (@hazeljs/<package>)

Quick validation checklist

Run these checks before merging docs changes:

# One command for local and CI validation
npm run docs:quality

This command checks stale command/version patterns, malformed import snippets, required metadata files, and JSON parse validity. It also checks metadata version alignment, lastUpdated freshness, package graph parity, and package docs coverage.

Metadata synchronization policy

When package APIs change:

  1. Update package docs in src/content/docs/packages/*.mdx
  2. Update relevant guides in src/content/docs/guides/*.mdx
  3. Update public/api/api-schema.json and public/api/packages-index.json
  4. Update public/api/dependencies.json if package relationships changed
  5. Verify links and examples still match released package behavior

PR review rubric (docs + metadata)

  • Correctness: examples compile conceptually and match current package APIs
  • Consistency: command names and terminology are uniform
  • Completeness: docs and JSON metadata are updated together
  • Discoverability: cross-links exist to related packages/guides
  • LLM safety: no contradictory snippets across similar pages

Suggested release gate

For releases, include a "docs parity" check:

  • npm run docs:quality passes
  • Metadata files updated with release version/date
  • At least one quick-start flow manually validated end-to-end