From e89cf2b278a8bd46943d7f9a2d2fb7a23176d680 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 3 Jun 2026 13:58:14 -0400 Subject: [PATCH] docs(plans): design for per-component reference docs in docs/components/ Brainstormed design: generate 25 StyleGuide-conformant developer-reference docs derived from src/ code (pilot AuditLog, then parallel fan-out, then accuracy/conformance verification). Complements the requirements specs; leaves src/, XML docs, and specs untouched. --- ...6-06-03-component-reference-docs-design.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/plans/2026-06-03-component-reference-docs-design.md diff --git a/docs/plans/2026-06-03-component-reference-docs-design.md b/docs/plans/2026-06-03-component-reference-docs-design.md new file mode 100644 index 00000000..64e7c32f --- /dev/null +++ b/docs/plans/2026-06-03-component-reference-docs-design.md @@ -0,0 +1,127 @@ +# Component Reference Documentation — Design + +Generate a complete set of per-component developer-reference documents in +`docs/components/`, derived from the actual `src/` code and written to +`StyleGuide.md`. This is the design produced by the documentation-audit +brainstorming session; the goal is documentation that is accurate (matches the +code) and complete (one doc per component). + +## Goal + +Produce 25 new reference docs — one per component — that describe **how the code +works** for a developer, with real code examples. These complement (do not +replace) the existing `docs/requirements/Component-*.md` design specs: the specs +say *what the component should do and why*; the new reference docs say *how the +shipped code does it*. + +The requirements specs, the `src/` code, and the XML doc comments are **not** +modified by this work. + +## Scope + +One reference doc per component, PascalCase, 1:1 with the existing spec set (minus +the `Component-` prefix), under a new `docs/components/` folder: + +``` +docs/components/ + README.md # index linking all 25, one-line description each + AuditLog.md CentralUI.md CLI.md ClusterInfrastructure.md Commons.md + Communication.md ConfigurationDatabase.md DataConnectionLayer.md + DeploymentManager.md ExternalSystemGateway.md HealthMonitoring.md Host.md + InboundAPI.md ManagementService.md NotificationOutbox.md NotificationService.md + Security.md SiteCallAudit.md SiteEventLogging.md SiteRuntime.md + StoreAndForward.md TemplateEngine.md TraefikProxy.md Transport.md TreeView.md +``` + +23 of the 25 map 1:1 to a `src/ZB.MOM.WW.ScadaBridge.` project. The other +two are documented in full (decision: keep `docs/components/` parallel to the +spec set): + +- `TraefikProxy.md` — no C# project; documented from the `docker/` / `infra/` + Traefik configuration and the Host `/health/active` active-node endpoint. + Examples in `yaml` / `bash` / `json`. +- `TreeView.md` — a Blazor component inside the CentralUI project; documented from + the actual `.razor` / `.cs` component code. Examples in `razor` / `csharp` / `css`. + +A link from the root `README.md` points to the new reference set. + +## Per-Document Structure + +Each doc follows the StyleGuide section organization (general to specific), +adapted to a code-reference doc. Sections scale to the component — simple +components omit sections they do not need. + +1. `#` H1 title (Title Case, matching the spec) + 1–2 sentence purpose. +2. `## Overview` — what it is, where it runs (central / site), its role and the "why". +3. `## Key Concepts` — domain terms a developer must know (only if needed). +4. `## Architecture` — main types (actors / services / entities), data and message + flow, with real `csharp` snippets (5–25 lines, with class context) taken from + the actual source. +5. `## Usage` — primary entry points and how the component is invoked, with real code. +6. `## Configuration` — `appsettings` sections / options classes as a table + (Option | Default | Description); only keys that exist in code. +7. `## Dependencies & Interactions` — what it depends on and talks to, cross-linked. +8. `## Troubleshooting` — common failure modes / health signals (where applicable). +9. `## Related Documentation` — link to the spec (`../requirements/Component-.md`), + related component reference docs, and relevant `AkkaDotNet/` notes. + +## Generation Workflow + +Approach: pilot exemplar, then parallel fan-out, then verification. + +### Phase 1 — Pilot + +Author `AuditLog.md` by reading the `src/ZB.MOM.WW.ScadaBridge.AuditLog` project +and its existing spec, fully StyleGuide-conformant. AuditLog spans central and +site, actors, database, telemetry, and configuration, so it exercises every +section and makes a strong template. The pilot is reviewed and approved before +fan-out. + +### Phase 2 — Fan-out + +One subagent per remaining component, dispatched in batches of roughly five to +six concurrently (`model: sonnet`). Each subagent receives: + +- The approved exemplar as the literal template to mirror. +- A condensed StyleGuide checklist (tone, present tense, real code only, names + match code exactly, language-tagged code blocks, relative links, a + Related Documentation section, no marketing words, no dates or version numbers). +- Its `src/` project path, to read the real code. +- Its existing `docs/requirements/Component-.md` spec, for domain + cross-check (where code and spec disagree, the code wins). +- The fixed section template and the output path. + +Each subagent returns the written doc and the list of source files it drew from. + +### Phase 3 — Verification + +For each generated doc, a reviewer pass checks: + +- Every type, method, file, and config key referenced exists in the source + (grep-verifiable). No invented APIs. +- StyleGuide conformance: heading casing, language-tagged code blocks, present + tense, no banned marketing words, no dates / version numbers, links resolve. +- Required sections present (at minimum Overview, Dependencies & Interactions, + Related Documentation). + +Flagged issues are fixed. Then the `docs/components/README.md` index and the root +README link are added, and all internal links are confirmed to resolve. + +## Acceptance Criteria + +- **Accuracy** — no invented code; every snippet, type, method, and config key + verifiably exists in `src/`; cross-links resolve; described behavior matches code. +- **Completeness** — 25 docs, none missing; each has at least Overview, + Dependencies & Interactions, and Related Documentation; index and README updated. +- **Conformance** — passes the StyleGuide checklist. + +## Out of Scope + +- No changes to `src/` code, XML doc comments, or the `docs/requirements/` specs. +- Nothing is committed mid-generation; the full set is reviewed before any push. + +## Related Documentation + +- [Documentation Style Guide](../../StyleGuide.md) +- [docs/requirements/](../requirements/) — the component design specs the code implements +- [README.md](../../README.md) — master component index