Skip to content

docs(chart): slim README 699->298, link to canonical docs#525

Merged
trilamsr merged 1 commit into
mainfrom
refactor/chart-readme-slim
Jun 4, 2026
Merged

docs(chart): slim README 699->298, link to canonical docs#525
trilamsr merged 1 commit into
mainfrom
refactor/chart-readme-slim

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Slimmed install/kubernetes/tracecore/README.md from 699 → 298 lines
(-401 LoC, -57%). The chart README had grown into a third operator
manual, duplicating canonical docs the repo already maintains.

What was cut

  • Per-knob values essays — the 56-row narrative values table is now
    a top-level group pointer. Authoritative per-knob commentary already
    lives in values.yaml (post-Lane-L trim).
  • Recipe walkthroughs (DCGM scrape config, OTLP exporter field
    reference, vanilla Prometheus pod-SD job, Loki/Tempo/Datadog hints,
    journald details) → pointers to docs/integrations/.
  • Operator-incident playbook prose in Troubleshooting (verbose
    rollout-math paragraphs, line-by-line probe arithmetic, kubelet probe
    state-machine narrative) → pointer to docs/RUNBOOK-tracecore.md,
    bullets only for chart-install gotchas.
  • PSS compliance table collapsed into a single-paragraph defaults
    summary; conftest + CI remain the load-bearing enforcement.
  • Production-preset prose trimmed to bullet rationale + canonical
    apply snippet.

What was kept (load-bearing)

  • All install/upgrade/uninstall commands.
  • All anchors inbound refs depend on: #troubleshooting,
    #values-reference, #common-configurations, and the section
    headings "Install", "Upgrade", "Upgrade posture", "Production
    preset", "Pod Security Standard compliance", "Documented deviations".
  • Canonical-doc pointers up top so first-time readers route immediately.

Cross-refs preserved

Pre-flight grep verified these inbound refs still resolve:

  • docs/getting-started.md — file-level ref, unchanged.
  • docs/reference-architectures/01-single-cluster.md
    #troubleshooting, #values-reference, #common-configurations
    anchors preserved.
  • docs/reference-architectures/README.md — file-level ref, unchanged.
  • install/kubernetes/tracecore/values-production.yaml — §"Production
    preset" heading preserved.
  • install/kubernetes/tracecore/templates/networkpolicy.yaml
    §"NetworkPolicy" content covered under #common-configurations.
  • docs/rfcs/0008-auto-update-boundary.md — §"Upgrade" / §"Upgrade
    posture" preserved.
  • docs/integrations/cert-manager-mtls.md — file-level ref, unchanged.

(Pre-existing line-number-anchored refs in
docs/v1-rc1-operational-gaps.md describing the README as stale will
need a separate sweep — they document drift this PR partly addresses.)

Test plan

  • wc -l install/kubernetes/tracecore/README.md → 298 (< 300).
  • make doc-check green pre + post (1115 markdown links + 218
    anchor slugs resolve).
  • All inbound refs grep-verified to still resolve.
docs(chart): slim install/kubernetes/tracecore/README.md from 699 to 298
lines. Recipe walkthroughs moved to docs/integrations/, operator
incident playbook to docs/RUNBOOK-tracecore.md, per-knob essays
deferred to values.yaml. All anchored cross-refs preserved.

Signed-off-by: Tri Lam <tree@lumalabs.ai>
@trilamsr trilamsr enabled auto-merge (squash) June 4, 2026 02:33
@trilamsr trilamsr merged commit 13ba00e into main Jun 4, 2026
16 checks passed
@trilamsr trilamsr deleted the refactor/chart-readme-slim branch June 4, 2026 02:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant