Skip to content

ADR-072: Handling unrecognized documentation snippets

Category: development Provenance: guided-ai

Decision

When adding new code snippets to documentation, ensure they can be validated programmatically. The validation script categorizes snippets and validates them against appropriate schemas. Unrecognized snippets are flagged as warnings. For snippets that cannot be validated automatically, manually verify correctness before committing.

Rationale

Documentation drift causes user confusion when examples use incorrect field names or outdated structures. Programmatic validation catches most issues, but some snippets (external tools, partial configs) cannot be validated automatically. For these, we accept the limitation and require manual verification. The key is distinguishing between "intentionally skipped" (external/known) and "unrecognized" (potentially a validation gap).

Agent Instructions

When adding documentation examples: 1. Validatable snippets - Add sufficient context for auto-detection: - K8s resources: Include apiVersion and kind - Helm values: Include recognizable top-level keys (operator, keycloak, etc.) - CR examples: Include apiVersion: vriesdemichael.github.io/v1 and kind

  1. Partial snippets - Add detection hints when possible:
  2. For env arrays: Keep the env: key as wrapper
  3. For spec sections: Include the spec: wrapper

  4. For config fragments: Include parent key context

  5. External/third-party snippets - These are intentionally skipped:

  6. CNPG partial configs (bootstrap, backup, certificates)
  7. FluxCD, Prometheus, cert-manager resources
  8. ingress-nginx Helm values

  9. Spring/application config examples

  10. Manual validation required - For snippets that can't be auto-validated:

  11. Verify against official documentation before committing
  12. Document the source/reference in a comment if helpful
  13. Consider if the snippet can be restructured for validation

Run task quality:validate-docs or uv run --group dev python scripts/lib/schema_validator.py to check validation status. The script will warn about new unrecognized snippets.

Rejected Alternatives

Validate everything or reject unvalidatable snippets

Some documentation necessarily shows external tool configs (CNPG, FluxCD) that we don't control schemas for. Removing these would make docs incomplete.

Skip validation for all partial snippets

Many partial snippets (env arrays, K8s affinity/resources) can be validated with proper schema extraction. Blanket skipping would miss validation opportunities.