docs: apply Simplified Technical English to site_docs - #19
Merged
Conversation
Expand the STE rule in CLAUDE.md from code comments and docstrings to all generated text: user-facing strings, site_docs, README, and commit messages. Add a rule that tells you to keep site_docs/ up to date with each change, and to keep the example code in site_docs/ identical to example_projects/. Rewrite all 24 pages in site_docs/docs/ in STE: active verbs, short sentences, no -ing forms, no present perfect, and no ambiguous words. Also correct four errors that the sweep found: - The clair init prompt in quickstart.md and cli/init.md showed the text from before #16. - The routing collision warning in guides/routing.md showed the text from before #16. - guides/incrementality.md showed a static date filter for APPEND. The example now uses clair.run_mode, as example_3 does. - concepts/index.md said "three" concepts, but listed four. guides/selectors.md said all commands accept --select, but its own table lists three that do not. 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.
Follow-up to #11, #15, and #16, which applied STE to
src/,tests/,example_projects/, andREADME.mdbut never touchedsite_docs/.CLAUDE.md
site_docs/,README.md, commit messages, and PR descriptions.site_docs/docs/, and to keep the example code in the docs identical toexample_projects/.The sweep
All 24 pages in
site_docs/docs/now follow STE: active verbs, short sentences, no-ingforms, no present perfect, and no ambiguous words such ascheckorverify.Errors that the sweep found
The docs had drifted from the code. Four fixes:
quickstart.md,cli/init.mdclair initprompt showed the text from before #16.guides/routing.mdguides/incrementality.mdexample_3builds the SQL withclair.run_mode, thus a full refresh reads all rows.concepts/index.md,guides/selectors.mdindex.mdsaid "three" concepts but listed four.selectors.mdsaid all commands accept--select, but its own table lists three that do not.example_3/derived/customer_order_summary.pyalso gets a docstring fix, so that it stays identical to the copy in the docs:Clair→clair, and one passive sentence made active.Checks
uv run pytest tests/— 516 passedmkdocs build --strict— clean, so no links broke🤖 Generated with Claude Code