docs: rewrite the README opening and jargon walls for a first-time reader#2687
Conversation
…ader State who the platform is for and that it is a working system rather than a product. Break the OpenBao prerequisite and the local-cluster paragraph into plain sentences and a scannable file list. Keep both diagrams in the templating section but defer file-level mechanics to docs/TEMPLATING.md, and drop the maintainer aside from the IMPORTANT callout. Component inventory, docs index, and cost table are unchanged. Fixes #2686
Reading the rendered page showed the Usage callout restating the same SOPS/OpenBao/postBuild detail the Prerequisites section now explains in plain words. The callout is only about what a fork must swap out, so it says that and nothing else. Also finish the prerequisite bullets left in the old terse style.
@codex review for documentation clarity: whether the rewritten README opening, prerequisites, and Usage section stay factually accurate about the SOPS/OpenBao secret flow and the local opt-in overlays, and whether any instruction present in the previous version was dropped. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a85cad57f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex review found that plainer wording had made five claims wrong. Verified each against the manifests before fixing: - Flux does not watch this repo; the Kustomizations reference an OCIRepository, so say the manifests are published and pulled. - OpenBao is not the runtime path for everything committed here. Bootstrap-critical values plus Dex/oauth2-proxy are still substituted into manifests by Flux postBuild; restore the "most secrets" split. - CI does not boot a cluster. It runs workload validate and scan only, so "exercised the same way" overstated its coverage. - The local overlay enables the CloudNativePG operator, not PostgreSQL. The apps overlay is resources: [], so no database exists locally. - KEDA request-rate autoscaling is opt-in, not core. Only VPA is core. The lesson is that simplifying prose can quietly drop qualifiers that were load-bearing; each of these was a qualifier doing real work.
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Readiness record. Promoting on all three conditions:
Confirmed merging this does not deploy prod: Codex's five findings on the first pass were all genuine accuracy regressions introduced by simplifying the prose — each verified against the manifests before fixing, with evidence in the individual thread replies. |
1 participant
Why
The platform README is the page a stranger lands on, and it was written from memory rather than for
a reader. It never said who it is for, stacked six unexplained product names into one prerequisite
bullet, and buried the local-cluster instructions in a twelve-line paragraph with file paths
mid-sentence.
What
The opening now says what this is, who it is for, and honestly that it is a working system rather
than something packaged for reuse. The secrets prerequisite and the local-cluster instructions are
plain sentences and a scannable list. The templating section keeps both diagrams but stops
restating what
docs/TEMPLATING.mdalready documents.This is a readability change, not a trim — the component inventory, docs index, and cost table are
untouched, so overall length is about the same.
Docs-only: no manifests changed, so no cluster validation applies.
Fixes #2686
Part of monorepo#2225