Conversation
jph00
requested changes
Jul 27, 2026
| 21. Decorative verbs: an inanimate subject whose verb is not what actually happens, with no person hidden. The sentence states a property or a mechanical event, and the verb arrived for vividness: "native ids ride in summary rows", "an id earns its place", "media hang identity at different levels". Nothing rides or earns; say what happens: ids appear in rows, an id qualifies, media attach identity. The subject may stay inanimate; the verb must be the plain word for the event. Standard technical vocabulary is not decoration: a span opens with its heading, you walk the tree, recursion bottoms out, a cache goes stale. Those are the words a maintainer says at a whiteboard, and the test is exactly that: would you say this verb at the whiteboard, or did it arrive for texture? The banned "land" and "shape" entries below are instances of this tell. | ||
| 22. Explanation colons: a colon gluing an assertion to its explanation, both halves full clauses ("the address layer has no semantic gaps: every failure is a verification failure"). A colon is for introducing a list, an example, or a definition. An explanation is a sentence, so give it a period. (Tell 2 is the label form of this, where the left half is a stub rather than a clause.) These accumulate one defensible instance at a time in dense technical prose, until every sentence has the same claim-colon-reason shape. | ||
| 23. Undefined jargon: tell 20's twin, in the other direction. Tell 20 repeats what the audience knows; this assumes what it doesn't. A term of art dropped without definition ("consistent with the glidepath", or "carrier" in a design doc) loses the reader from that sentence on. The two tells are one audience judgment. Name the audience, cut what they know, and define what they don't at first use, or use a plain word instead. Needed jargon is fine; unexplained jargon is not. | ||
| 24. Category-then-unpack: an abstract category phrase, a colon, then a parallel list unpacking it: "it should see what you have been doing: the cells you ran, what they printed, the plots you drew, the errors you hit". The sentence says everything twice, once vaguely and once itemized, and the items fall into tell 10's parallel cadence. Cut one side: enumerate directly as the sentence's own object ("it should see the cells you ran and what they printed"), or name the category and trust it ("it should see your session so far"). A colon-introduced list is fine when the lead-in genuinely needs the items to be understood; it's the tell when the lead-in is a dummy the list then restates. |
Contributor
There was a problem hiding this comment.
Cut one side: enumerate directly as the sentence's own object - @ncoop57 try to make sure write_prose's prose does not itself contain any tells! This : should go. "Cut one side" is repeating what the rest of the sentence says!
Author
There was a problem hiding this comment.
Ooof, good catch. Thanks Jeremy, I fixed it.
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
2 participants
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
Adds a new anti-pattern — tell 21: Category-then-unpack — to the
write_proseskill docstring.The construction is an abstract category phrase, a colon, then a parallel list that restates it:
The sentence says everything twice — once vaguely, once itemized — and the items fall into tell 10'''s parallel cadence.
Changes
a rich tapestry of innovation: the tech we build, the deals we strike, the grids we green[21]).