docs: rewrite the README and usage guide in plain language - #36
Merged
Conversation
The docs leaned on metaphor where a plain description was available -- an
ARXML called an "interface contract", an A2L a "calibration surface", a
single-model regen called a "fingerprint". A reader who knows AUTOSAR but
not this codebase gets nothing from those, and the Vietnamese translation
turned them into literal nonsense ("hop dong interface").
Every concept is now defined before a rule is built on it, the rename and
reorder conditions became lists instead of chained prose, and the reasons
given are the ones a user cares about rather than the internal design rule.
The README also gained the consistency check, which shipped in 1.10/1.11 and
was never documented there, plus the logo header.
Same content throughout: the flag table, the noise rules, the exit codes and
every anchor are unchanged.
The rewrite that preceded this commit fixed the same four faults over and over, so they are worth stating once rather than rediscovering: define a concept before leaning on it, drop metaphor where a plain description fits, give the user's reason instead of the internal design rule, and break chained conditions into a list. The translation rule is the one that cost the most: docs/vi renders the meaning, not the words, and because the English file is the source of truth a fix that changes what a sentence claims has to land on both sides or they diverge silently.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
The README,
docs/usage.mdand both Vietnamese translations are rewritten. Nobehaviour change — this is prose only.
The docs leaned on metaphor wherever a plain description was available: an
ARXML was called an "interface contract", an A2L a "calibration surface", a
single-model regen "the fingerprint of a quick regen". A reader who knows
AUTOSAR but has never seen this codebase gets nothing from those, and the
Vietnamese side had translated them literally into meaningless phrases
("hợp đồng interface", "bề mặt calibration").
Concretely:
its interface contract" became "its ARXML declares which ports, runnables and
events the model has".
into one paragraph; the reorder rule did the same. Both are lists now.
is a separate category is now "a rewritten comment you can skim, a renamed
identifier you have to check" instead of a restatement of the fail-safe rule.
1.11 and had never been mentioned there.
Also in this PR
CLAUDE.mdgains section 10, recording the four rules above plus thetranslation rule, so the next docs change does not rediscover them. Workflow
moved from section 10 to 11; nothing else references section numbers.
For the reviewer
Content is unchanged throughout — the flag table, every noise rule, the exit
codes and every
#anchorare identical to before, so no inbound link breaks.Worth a check that the technical claims still read correctly, particularly the
ARXML/A2L definitions in the consistency-check section, since that is the part
where the wording changed most.
python -m unittest discover -s tests— 715 passed.