Rewrite the documentation and docstrings to the prose standard - #77
Merged
Merged
Conversation
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.
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.