docs: apply Simplified Technical English to user-facing strings - #16
Merged
Conversation
Rewrite the strings that a clair user reads, following ASD-STE100: active verbs, short sentences, no -ing forms, no present perfect, and one meaning per word. Covers CLI help text and prompts, error messages, log detail fields, the comments in the generated MERGE statements, the docs= values in the example projects and fixtures, and the column-inference messages in the docs UI. Test assertions that match on message text follow the new wording. No behaviour changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
main #15 rewrote comments and docstrings in STE, which overlapped three files. Resolutions: - cli/main.py: keep main's docstrings for `compile` and `docs`; keep this branch's "configuration" over the "config" abbreviation for `init`. - core/compiler.py: main's docstring, this branch's summary line. - core/scaffold.py: main's wording for the generated environments.yml comments. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
Applies ASD-STE100 to the strings a clair user actually reads.
CLAUDE.mdalready requires STE for comments and docstrings; this extends the same rules to output.Rules applied: active verbs, ≤20-word instructions / ≤25-word descriptions, no
-ingforms, no present perfect, one meaning per word, and no vague verbs (check,ensure).Scope
cli/main.pyexceptions.py,trouve.py,test.py,run_config.py,dag.py,routing.py,environments.py,runner.py,compiler.pydetail=fieldscli/main.pytrouve.py(the 3 UPSERT statements)docs/columns.pyenvironments.ymlcommentscore/scaffold.pydocs=valuesexample_projects/,tests/fixtures/,README.mdLog event keys (
run.node.success), machine tokens (reason="table_not_found"), and SQL keywords are unchanged — they are identifiers, not prose.Sample of the rewrites
Selector pattern to filter Trouves; supports globs and + operators→Pattern that selects Trouves. You can use globs and + operators.Run mode: full_refresh recreates all tables; incremental applies only new data.→Run mode. full_refresh writes all tables again. incremental writes only the new data.environments.yml not found at {path}. Run 'clair init' to create one→Clair cannot find environments.yml at {path}. Run 'clair init' to make one.Skip running data quality tests after a successful run.→Do not run the data quality tests after a successful run.This model uses SELECT * -- columns depend on the upstream source and cannot be inferred from SQL alone.→This model uses SELECT *. The columns come from the upstream source, thus Clair cannot find them in the SQL.docs="Daily order totals aggregated from raw orders."→docs="Daily totals for the orders. This Trouve reads the raw orders."Verification
uv run pytest tests/— 516 passed. 37 tests assert on message text and were updated to the new wording; no test logic changed.ruff check .— clean.clair --helpand the per-command help render correctly.No behaviour changes.
🤖 Generated with Claude Code