diff --git a/docs/clientdocs-workflow-review-20260708.md b/docs/clientdocs-workflow-review-20260708.md new file mode 100644 index 0000000..b5c1aa2 --- /dev/null +++ b/docs/clientdocs-workflow-review-20260708.md @@ -0,0 +1,190 @@ +# clientdocs workflow review + consolidation proposal (2026-07-08) + +STATUS: PROPOSAL for operator ruling. Read-only analysis; nothing implemented. +Options are presented per finding; the operator rules before any change. No +identifier numbers are consumed here -- they are assigned at implementation. + +## Why this exists + +Operator's stated problem (2026-07-08): the information a client needs is spread +throughout the handover documentation with no clear flow. A client has to switch +between multiple documents to accomplish one task, and some workflows have holes +that cause errors (the flannel network-driver gap being the live example: a +self-created flannel cluster never converges, and devteam lost a night to it). +The goal for the client-facing set: an easy-to-follow, workflow-shaped path that +makes finding and using their data simple, minimizes document-switching, and +carries enough component detail that the client understands what each piece +does. + +DOCFIX-123 (the new jenkins-kubernetes-guide.md) is the first instance of the +target shape -- a single self-contained workflow that cross-links to detail +rather than scattering it. This review proposes applying the same principle +across the rest of the set. + +## Method + +Read-only inventory of all 20 client-facing files under clientdocs/ (the six +top-level guides, the tenant-skill SKILL.md + four references, and the six +starter-kit scripts), mapping every workflow topic to the file(s) that cover it, +plus duplication, cross-file conflicts, and gaps. Evidence is file:line +throughout the source inventory; the summary below carries representative cites. + +## The client journey (what a client actually does, in order) + +1. Pre-onboarding homework (intake-form.md). +2. Receive credentials + first orientation (welcome.md, handover-pack.md). +3. Prove the tenancy works (acceptance-checklist.md). +4. Run day-to-day (self-service-guide.md; tenant-skill references). +5. Connect automation / CI (ci-integration-guide.md). +6. Stand up a Kubernetes + Jenkins workflow (jenkins-kubernetes-guide.md, new). + +The docs exist for every stage, but stages 2-6 repeat each other's content and +none of them states "you are here, read these in this order." + +## Findings + +### F1 -- Heavy duplication (maintenance-drift + reader confusion) + +The same facts are authored independently in many files. Representative: + +- The three-account model table: 4 renderings (handover-pack.md:28-32, + self-service-guide.md:10-14, tenant-skill/SKILL.md:32-36, and prose in + welcome.md). +- The clouds.yaml auth block: 3 byte-identical copies (ci-integration-guide.md, + tenant-skill/SKILL.md, scripts/clouds.yaml.template). +- "Cluster create cannot use an application credential": stated in 8 places. +- The worked CI sequence: duplicated at length in ci-integration-guide.md and + references/ci-automation.md. +- Floating-IPs-count-when-detached: repeated in 5 files. +- (Full list: 15 duplication clusters in the source inventory.) + +Risk: any change (an endpoint, an account name, a rule) must be made in N places +or the copies drift. It also makes each document longer than it needs to be, +which is itself part of the "hard to follow" problem. + +### F2 -- No single entry point or reading order + +No file tells the client which document to open first, or the order for a given +goal. A client wanting "deploy my app to Kubernetes from Jenkins" previously had +to assemble it from kubernetes.md + ci-integration-guide.md + day2-operations.md ++ troubleshooting.md. (DOCFIX-123 now owns that one journey; the other journeys +still lack a spine.) + +### F3 -- Workflow holes that cause errors + +- Network-driver choice: the self-service path (self-service-guide.md:89-99) + never mentioned calico, so a client building a template via the dashboard got + no steer away from flannel. CLOSED 2026-07-08 in kubernetes.md + the Jenkins + guide; self-service-guide.md still only carries the Public/Hidden rule, not + the driver rule. +- Right-sizing to host capacity: every doc presents quota as the only ceiling on + node_count (self-service-guide.md:91, kubernetes.md:49, welcome.md, intake). + None warned that an under-quota-but-oversized request fails with "No valid + host" -- the exact failure devteam hit. CLOSED in the Jenkins guide; NOT yet + in the general docs. + +### F4 -- Partial component detail / no glossary + +Component terms (application credential, the -cluster account, cluster template, +kubeconfig, LoadBalancer Service, floating IP, ingress) are defined inline where +first used but there is no single glossary a client can consult. The operator +specifically asked for "enough detail so they understand what all the components +do." The Jenkins guide added a scoped glossary (section 10); the set has no +shared one. + +### F5 -- Cross-file inconsistencies + +- Jenkinsfile.example calls scripts at clientdocs-starter-kit/... while the kit + is delivered as scripts/ (README.md:27-33). The file admits paths need + adjusting, but it is a stumble. +- Jenkinsfile.example's "Worked sequence" stage runs an infrastructure smoke + build, not an app deploy -- misleading under that name for a k8s reader. + +## Proposed information architecture + +Principle: each fact has ONE owner; every other mention is a one-line pointer, +not a copy. Each guide owns a JOURNEY (a workflow) and cross-links to the owners +for reference detail. This is the shape DOCFIX-123 already demonstrates. + +Proposed owners (single source of truth): +- Identifiers, endpoints, CA bundle, the full account model: handover-pack.md + (already the most complete; make it canonical). +- clouds.yaml / OS_* auth setup: scripts/clouds.yaml.template (the delivery-ready + copy) + one reference section; others point to it. +- Day-2 resource operations (networks, servers, load balancers, secrets): + references/day2-operations.md. +- Troubleshooting signatures: references/troubleshooting.md (the single triage + ladder; other docs link symptoms to it). +- Journeys (own the flow, link the detail): welcome (orientation), + self-service-guide (day-to-day), acceptance-checklist (proof), + ci-integration-guide (automation), jenkins-kubernetes-guide (k8s+Jenkins). + +Add: +- A top-of-set "Start here / reading order" -- either a short new index doc or a + section in welcome.md -- mapping goal -> ordered doc list. +- A shared glossary -- a new small reference, or a section in handover-pack.md -- + that every guide links to (retire the per-guide inline definitions in favor of + one, keeping only a one-line gloss at first use + a link). + +## Consolidation moves (OPTIONS for operator ruling) + +Each move is independent; rule per-move. Effort/risk are rough. + +- M1 -- De-duplicate the account model. Own it in handover-pack.md; replace the + other 3 renderings with a 1-line summary + pointer. + Options: (a) do it; (b) keep the self-service copy (first-read convenience) but + retire the SKILL.md + welcome copies; (c) leave as-is. + Effort: low. Risk: low. Recommend (b) -- one convenience copy, not four. + +- M2 -- De-duplicate clouds.yaml/auth. Own in clouds.yaml.template; the CI guide + and SKILL.md point to it. + Options: (a) do it; (b) leave. Effort: low. Risk: low. Recommend (a). + +- M3 -- Add a "Start here / reading order" entry point. + Options: (a) new short index doc; (b) a section in welcome.md; (c) none. + Effort: low. Risk: low. Recommend (b) -- no new file to package. + +- M4 -- Shared glossary. + Options: (a) new reference file linked from all guides; (b) a section in + handover-pack.md; (c) leave per-guide inline. Effort: medium (touches many + files if links are added). Risk: low. Recommend (a). + +- M5 -- Close the remaining F3 holes in the general docs: add the driver rule and + the host-capacity/right-size caveat to self-service-guide.md (and anywhere + node_count is discussed). + Options: (a) do it; (b) rely on the Jenkins guide + kubernetes.md only. + Effort: low. Risk: low. Recommend (a) -- these are the error-causing holes the + operator called out. + +- M6 -- Fix F5: correct Jenkinsfile.example's script paths to scripts/ and either + rename or re-scope its misleading stage; consider adding a second + Jenkinsfile.example for the kubeconfig-deploy pattern (or point at the Jenkins + guide's inline pipeline). Effort: low-medium. Risk: low (starter asset). + Recommend: fix paths now; the deploy-pipeline example already lives in the + Jenkins guide, so just cross-link. + +- M7 -- Reconcile the quota-vs-capacity expectation cloud-side (separate from + docs): the addendum-40 finding that testcloud tenant quotas over-promise + schedulable capacity. Doc side is M5; the cloud side (trim quotas to reality) + is an operator decision logged in addendum 40. + +## Recommended sequencing + +1. M5 first (closes the active error-causing holes; low effort). +2. M3 + M1(b) (entry point + de-dup the worst offender; makes the set navigable). +3. M2, M6 (mechanical de-dup + the starter-asset fix). +4. M4 (glossary; larger touch, do once the owners above are settled). + +Each move ships under the standard clientdocs discipline (ASCII/LF, no +internal-term leakage, L7 receipt re-record, harness green, changelog + revert) +and, where a delivered client already has the affected file, a package +re-instantiation. Numbers are assigned at implementation, not here. + +## Not in this proposal + +- The broad rewrite into a single mega-document. The operator's goal is + minimize doc-switching PER TASK, which the journey-owns-flow + cross-link model + achieves without collapsing the set into one unnavigable file. If the operator + prefers fewer, larger documents, that is a different architecture to rule on. +- Any client-specific content. This is about the template set; per-client + instantiation is unchanged. diff --git a/logs/as-executed-index.md b/logs/as-executed-index.md index 378296e..4ad815f 100644 --- a/logs/as-executed-index.md +++ b/logs/as-executed-index.md @@ -11,3 +11,4 @@ | 2026-07-06 | ops-snapshot-devteam-gate | jesse.austin (Claude Code lane) | pre-devteam-onboarding cloud snapshot (first live cloud-snapshot.sh run) | | 2026-07-06 | d074-phase0 | jesse.austin (Claude Code lane) | D-074 Phase 0: overlap+Magnum proof via foil1 (exact-overlap subnet + cluster + API-LB), teardown, cloud-assert | | 2026-07-07 | ops-devteam-onboard | jesse.austin (Claude Code lane) | devteam onboarding window: stages 0-4 + tenant-assert + canary on 10.100.0.0/24 (D-074 fallback, first client-facing run); capi-test-1 delete ruled + staged (operator to run) | +| 2026-07-08 | ops-decommission | jesse.austin (Claude Code lane, per-command wrap) | decommission window: lbtest LB reclaim + beta-cluster teardown + foil1 offboard (first offboard v2 --apply; E0 always-403 defect logged) + magnum orphan-sweep audit (clean); open/close cloud-assert PASS |