docs: state the mechanism directly in the entry-point READMEs - #91
Merged
Conversation
The root README, the model-switch example and the coverage index mixed two kinds of prose. The reference sections read as documentation; the introductory sections read as narration, with fragments used for emphasis, behaviour staged as a sequence of events, and unnamed people standing in for the component doing the work. A reader arriving at the repository meets the narrated sections first, which are the hardest to skim and the slowest to answer "what does this do and how". Those passages now state the condition, the mechanism and the result directly, with the policy, the score or the threshold as the grammatical subject. Every claim, figure, link and heading target is unchanged, the "Jump to" anchors still resolve, and opa check, regal lint, check-anchors.sh, check-version-refs and model-card-coverage --check all pass. Two substantive corrections ride along: - 4321e7a moved the EU field split to 170 declarations and 15 measurements but left the next sentence reading 14. It now reads 15. - "The problem" described an AI system as changing on the order of weeks. Model swaps, prompt edits and index rebuilds now land on the order of days.
The introductory sections of README.md, examples/model-switch/README.md and docs/coverage/README.md narrated behaviour as a sequence of events, while the reference sections already read as documentation. A reader arriving at the repository meets the narrated sections first. Those sections now state the conditions and the resulting policy outcome, with the score, the threshold and the rule as the subject. Several descriptions were also imprecise: - The model-switch caption described a live model swap. The example compares checked-in baseline and candidate toxicity metrics with the prompts, the scoring method and the policy held fixed. - "Why GOPAL" characterised the alternatives by naming vendors. It now describes what generic policy-as-code and proprietary governance platforms each supply, and where an open AI-regulatory policy library differs. - The declared/measured distinction now says why a supplied number remains a declaration unless the evaluator evidence behind it is supplied as well. - The EU AI Act figure is stated as 185 input-field reads rather than 185 fields, which is what the count measures; unique declared fields are fewer. Every claim, figure, link and heading target is preserved. opa check, regal lint, check-anchors.sh, check-version-refs.sh, check-test-coverage.sh, check-deprecations.sh, generate-coverage.sh --check and model-card-coverage.sh --check all pass.
12 tasks
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
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 this changes
Rewrites the introductory sections of the three entry-point READMEs so they read
as reference documentation rather than narration, and corrects several imprecise
descriptions. Documentation only; no
.regofile is touched.Type
v2/directory)Detail
README.md,examples/model-switch/README.mdanddocs/coverage/README.mdmixed two registers. Their reference sections read as documentation; their
introductory sections staged behaviour as a sequence of events, used fragments
for emphasis, and put unnamed people in place of the component doing the work.
Those sections now state the condition, the mechanism and the result, with the
policy, the score or the threshold as the grammatical subject.
Four descriptions were also imprecise and are corrected:
checked-in baseline and candidate toxicity metrics with the prompts, the
scoring method and the policy held fixed.
states what generic policy-as-code and proprietary governance platforms each
supply, and where an open AI-regulatory policy library differs. A Portable
point is added, covering
opa eval, Conftest, an existing OPA server andAICertify.
declaration unless the evaluator evidence behind it is supplied as well.
fields, which is what the count measures; unique declared fields are fewer.
An earlier correction rides along in
1685c11: 4321e7a moved the EU split to170 declarations and 15 measurements but left the following sentence reading 14.
Every claim, figure, link and heading target is preserved. Verified against the
tree: 29 EU AI Act policy files, and the 170/15/185 split unchanged from
main.Checklist
.regohas a sibling*_test.rego— n/a, no.regochangedREADME.mdlists the new policy — n/a, no new policyopa check --ignore custom/ .passes locallyregal lint --ignore-files custom/ .passes locallyv2/directory requiredAlso run locally, all passing:
check-anchors.sh,check-version-refs.sh,check-test-coverage.sh,check-deprecations.sh,generate-coverage.sh --check,model-card-coverage.sh --check.Source(s)
No regulation is encoded or reinterpreted by this PR.
Notes for reviewers
These two commits were pushed to
chore/zenodo-2-0-0-doiafter #90 had alreadymerged, so they were stranded on a closed PR's head branch and never reached
main. This PR carries them across unchanged; nothing is rebased or squashed.Four framework READMEs (
examples/github-actions/,industry_specific/,international/,international/uk/) carry one-line wording changes from1685c11and are included in the diff for that reason.Reviewing
86a986eand1685c11separately is easier than reading the combineddiff, since the second commit rewrites paragraphs the first had already touched.