Skip to content

docs: fix the docs that drifted from the code, add an architecture map and Vietnamese translations - #21

Merged
longvo92 merged 1 commit into
mainfrom
claude/engineering-documentation-85eea9
Jul 29, 2026
Merged

docs: fix the docs that drifted from the code, add an architecture map and Vietnamese translations#21
longvo92 merged 1 commit into
mainfrom
claude/engineering-documentation-85eea9

Conversation

@longvo92

Copy link
Copy Markdown
Owner

Why

The README described a tool that had moved on without it, and the one document a
newcomer most needs — how the pieces fit together — did not exist at all.

What changed

README corrections, each checked against the code rather than assumed:

  • The viewer section never mentioned Export report… / Ctrl+E, including the
    guarantee that it is built from the complete scan and not from what is on
    screen.
  • The module tree was missing view_model.py, syntax.py, review.py and
    gitsource.pyview_model.py is the seam that keeps the report and the
    viewer from disagreeing, and it was not named once.
  • The add-a-rule note skipped a2l_rules.py, skipped the shadow step, and asked
    for "a test" where the rule checklist requires two — the pattern alone, and
    the same pattern beside a real change.
  • --review did not say the badge hides changes already signed off.

docs/architecture.md — new: why the core is stdlib-only, what each of the
two diff passes decides, why the verdict lives in one function, what the result
dict guarantees downstream, and a "change X, touch Y" table.

docs/vi/ — Vietnamese README and architecture doc, for the team that reads
Vietnamese. Both say up front that the English files are authoritative, so a
stale translation cannot quietly become the thing someone trusts.

Stale facts fixed everywhere they appeared: build.ps1 has no -Exe switch
(the default builds the exe; -Pyz / -PyzOnly add or isolate the zipapp), the
smoke-render command in CLAUDE.md named a script that is not in the repo, and
the zipapp is ~110 KB — measured, not the 78–80 KB that README, CLAUDE.md and
build.ps1 all claimed.

Checks

  • python -m unittest discover -s tests — 378 tests, OK.
  • Every relative link in the four docs resolves.
  • No behaviour change: the only non-doc edit is a size figure in a build.ps1
    comment.

The tool is used by an automotive team that reads Vietnamese, and the two docs
a newcomer actually needs — what the tool does, and how it is put together —
were English only.

Both translations state up front that the English files are authoritative, so a
stale translation can never quietly become the thing someone trusts. The
English README and architecture doc link across to them.
@longvo92
longvo92 merged commit e5450a2 into main Jul 29, 2026
4 checks passed
@longvo92
longvo92 deleted the claude/engineering-documentation-85eea9 branch July 29, 2026 15:14
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