lmxopcua/docs/plans/2026-06-03-documentation-audit-design.md

Documentation Audit — Design

Date: 2026-06-03 Status: Approved (brainstorming complete) → ready for writing-plans Branch: docs/documentation-audit (off master @ c6d9b20)

Goal

Perform an in-depth audit of the live reference documentation to ensure accuracy and completeness, correcting issues in place and writing documentation for every shipped-but-undocumented feature.

Decisions

These were settled during brainstorming and are not open for re-litigation in the plan:

Dimension	Decision
Corpus	Live reference docs only — top-level docs/*.md current-reference set, docs/drivers/*.md, README.md, CLAUDE.md (32 files). Excludes docs/v1, docs/v2, docs/plans, docs/reqs, docs/v3, looseends.md.
Output mode	Fix in place, single pass → corrected docs + a change summary (delivered in chat, not committed).
Checks	All four dimensions: structural integrity, stale-status reconciliation, code-reality cross-check, completeness gaps.
Gap handling	Fill every gap — write documentation for all undocumented shipped features, small or large.
Approach	C — deterministic baseline → code-first inventory → grouped vertical passes.

Out of scope

• Historical tiers (v1/, v2/, plans/, reqs/, v3/, looseends.md) — they are point-in-time records and are not edited.
• The XML doc-comment pass (handled separately by the /fixdocs run on branch chore/fixdocs-xml-doc-comments).
• Code changes. This is a documentation effort. If the audit finds a genuine code bug, it is flagged in the summary, not fixed.
• Secrets must never be introduced into docs: sql_login.txt, pki/, and the dev gateway API key stay out of any committed file.

Corpus & subsystem grouping

Phase 1 runs one full-depth pass per group (G1–G4). G5 is the Phase-2 reconciliation group.

Group	Files
G1 — Server core & data path	OpcUaServer.md, AddressSpace.md, ReadWriteOperations.md, IncrementalSync.md, VirtualTags.md, ScriptedAlarms.md, AlarmTracking.md
G2 — Drivers	docs/drivers/: README.md, Galaxy.md, FOCAS.md, + 7 *-Test-Fixture.md (AbLegacy, AbServer, FOCAS, Modbus, OpcUaClient, S7, TwinCAT)
G3 — Security & operational	security.md, Redundancy.md, Reservations.md, ServiceHosting.md, StatusDashboard.md
G4 — Client & CLI tooling	Client.CLI.md, Client.UI.md, DriverClis.md, Driver.{Modbus,AbCip,AbLegacy,S7,TwinCAT,FOCAS}.Cli.md
G5 — Index & root (reconcile last)	docs/README.md, CLAUDE.md

Already-suspected findings (the design accounts for them; verify during the pass):

• Top-level AlarmTracking.md may be orphaned — the README index links to v1/AlarmTracking.md, not the top-level file. Resolve in G1.
• StatusDashboard.md is a stub pointer (superseded by v2/admin-ui.md). Resolve in G3.
• CLAUDE.md references both docs/security.md and docs/Security.md — a case mismatch that works on macOS but breaks on the Linux docker host. Resolve in G5.

Phase 0 — deterministic baseline + code-first inventory

Two transient working artifacts produced before any doc is edited, kept under a scratch dir and not committed (lesson from the fixdocs run, where OtOpcUa-docs-*.md cluttered the repo root):

(a) Structural checker. Walks all 32 docs, extracts every markdown link and inline source path (src/..., docs/..., scripts/..., tests/...), and resolves each against the filesystem. Output: broken links / dead paths / case mismatches. Deterministic and re-runnable — it is also the Phase-2 exit gate.

(b) Feature inventory from source. Enumerated from code, not docs, so "fill every gap" has ground truth:

• Drivers — the driver projects under src/Drivers/ (+ the Historian.Wonderware sidecar).
• Capabilities — the Core.Abstractions interfaces (IReadable, IWritable, ITagDiscovery, ISubscribable, IAlarmSource, IHistoryProvider, IHostConnectivityProbe, IPerCallHostResolver).
• Config surface — appsettings.json sections + bound Options classes (Security, Authentication.Ldap, Redundancy, MxAccess, …) and documented env vars (OTOPCUA_ROLES, …).
• CLI surface — command verbs + flags from the System.CommandLine definitions in the client + 6 driver CLIs.
• Security profiles — the values SecurityProfileResolver actually resolves.

Diffing the inventory against the docs yields the completeness worklist (what ships but is not documented) and grounds the code-reality cross-check.

Phase 1 — per-group fix methodology

Each group is a vertical pass. For every doc in the group, all four dimensions are applied in order, then the group is committed together:

1. Structural — apply the doc's Phase-0 link/path findings: repair broken links, repoint moved src/... paths to current locations, fix case mismatches, resolve orphans (re-link, merge, or retire), replace stub pointers with real content or a correct pointer.
2. Stale-status — locate state words / banners (blocked, pending, not yet, planned, TODO, as of <date>) and reconcile each against current reality (source + git history + known facts: v2 feature-complete, native alarms verified working). Rewrite to present-tense truth or delete if obsolete.
3. Code-reality cross-check — verify every technical claim (namespace, class, file, appsettings key, env var, CLI verb/flag, described behavior) against the Phase-0 inventory and a direct source read. Fixes go to the doc to match the code, never the reverse. A genuine code bug is flagged in the summary, not changed.
4. Completeness — take this group's slice of the inventory diff and write the missing docs: small inline additions for a missing key/flag, new sections or whole new pages for an undocumented driver/subsystem. Every new page is linked from its index (README.md / drivers/README.md).

Hard scope rule: edits land only in the 32 in-scope files. If an in-scope doc links into an out-of-scope tier and the target moved, fix the link in the live doc — never edit the historical artifact.

Phase 2 — reconciliation & validation

Cross-doc reconciliation (G5): docs/README.md index integrity (every listed doc exists and is correctly described; newly written docs are added), "superseded by" pointers correct, and CLAUDE.md reconciled against reality (the security.md/Security.md casing, retired-project notes, the docs it names as canonical).

Validation — the audit's "tests" are two re-runnable gates plus review:

• Structural gate — re-run the Phase-0 checker → zero broken links / dead paths / case mismatches.
• Completeness gate — re-run the inventory diff → every shipped feature is documented, or each deliberate exclusion is listed with a reason.
• Spot-verification — a sample of code-reality fixes re-checked against source with file:line citations in the summary.
• Each group is a reviewable commit; nothing touches code, secrets, or out-of-scope tiers.

Output

The change summary (in chat, not committed): fixes grouped by dimension, the list of new docs written for completeness, and any code bugs flagged-not-fixed.

Brainstorming task references

Native tasks created during brainstorming: #53 (explore), #54 (clarify), #55 (approaches), #56 (present design), #57 (write design doc), #58 (transition to writing-plans).