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.
This commit is contained in:
Joseph Doherty
@@ -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.<Name>` 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-<Name>.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-<Name>.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
|
||||
Reference in New Issue
Block a user