Skip to content

docs(readme): rework for user-facing clarity#73

Merged
ShortArrow merged 3 commits into
mainfrom
docs/readme-user-facing-pass
Jul 6, 2026
Merged

docs(readme): rework for user-facing clarity#73
ShortArrow merged 3 commits into
mainfrom
docs/readme-user-facing-pass

Conversation

@ShortArrow

Copy link
Copy Markdown
Owner

Summary

Addresses reader feedback that the README leans on internal jargon and internal architecture rather than the user's point of view. No functional change — docs only.

Changes

  • Terminology clarified. "script" is now defined as a SCPI script file (.scpi); "scenario" as a query → response rule set. The overlapping record bullets are consolidated into run a mock / capture then replay / run & lint SCPI scripts, and visa script is surfaced for the first time (linked to ADR 0027). All features referenced are verified present (MockScenarioCommand record --from-script, VisaScriptCommand).
  • use-first statefulness. The lead Highlights bullet now frames the current device like a shell's working directory: visa add registers, visa use selects, and later commands need no target at all.
  • Connection architecture over internal architecture. The Clean Architecture layer diagram is replaced with a scenario-based Mermaid diagram (drive hardware / test without hardware / expose a gateway / control plane). Section retitled How it connects; the internal layering is kept as a one-line pointer to ADR 0003 / ADR 0021 for contributors.
  • Samples labelled as test mocks. The Samples entry now states they are ready-made mock instruments for testing without hardware.
  • Scalable language links. Inline per-doc ([日本語]) / ([English]) links are removed; only the top-of-file switcher remains. Recorded in ADR 0024 §4 (navigation links point to the English canonical only, so index lines don't grow per added language).

Both README.md and docs/README.jp.md updated in lock-step (i18n sync check).

Verification

  • No stale #architecture anchors; ADR 0027 link resolves; only the two top switcher headers remain.
  • csharpier clean; pre-push correctly detected docs-only and skipped build + test.

@ShortArrow ShortArrow merged commit dcf400f into main Jul 6, 2026
5 checks passed
@ShortArrow ShortArrow deleted the docs/readme-user-facing-pass branch July 6, 2026 07:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant