Skip to content

Rewrite the documentation and docstrings to the prose standard - #77

Merged
peterbjohnson merged 8 commits into
devfrom
wb/t46
Sep 20, 2026
Merged

peterbjohnson merged 8 commits into
devfrom
wb/t46

Conversation

@peterbjohnson

Copy link
Copy Markdown
Member

The prose written into this repository over the last two days - docs/source/*.md, module and function docstrings, comments, error messages and CHANGELOG entries - uses a style the maintainer has rejected: implicit subjects, figurative verbs, pronoun objects and facts wrapped in rhetoric. Example, from docs/source/spec.md: "The last line is the point of it: a spec run reports every block it made nothing of, naming the lines it is, so what is left to account for is in front of you rather than quietly missing." It should read: "The last line illustrates the purpose of a spec. Blocks not matched to a field are reported, with their line numbers, so that all content is accounted for."

The standard is the writing-prose-here skill. Rewrite every sentence in docs/source/*.md (except the generated tables), the module docstrings and public docstrings of in2lambda/source, in2lambda/draft, in2lambda/spec, in2lambda/validation, in2lambda/json_convert and in2lambda/main.py, the comments in those files, the error messages the SourceError subclasses print, and CHANGELOG.md. Change no behaviour: the diff touches strings, docstrings and comments only, and the test suite passes unchanged except where a test asserts on the wording of a message, in which case the test is updated to the new wording. Prefer deleting a sentence to keeping a weak one. Done when a reviewer sampling twenty sentences at random finds none that breaks a rule of the skill.


Workbench ticket t46.

@peterbjohnson
peterbjohnson merged commit f89b528 into dev Sep 20, 2026
6 checks passed
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