# 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.
