Take the em dashes out of the documentation - #69
Closed
tonytonycoder11 wants to merge 1 commit into
Closed
Conversation
Every one of them, across the README, STABILITY.md, the migration guide, CONTRIBUTING.md and the 2.0.0 changelog section, plus the repository description. Twenty-two in total, replaced with the punctuation the sentence actually wanted: a colon before a list, a full stop between two independent clauses, commas around a real aside. The em dash is the most reliable tell that a text came out of a language model, and these are portfolio repositories whose readers are the people most likely to recognise it. That the files already used them is not a defence, because half of the ones removed here arrived recently. The mechanical boldface goes with it, for the same reason. STABILITY.md had nine paragraphs opening with a bolded sentence acting as a header, which is the same tell in a different shape: when every paragraph has an emphasised line, none of them is emphasised. Nineteen down to nine, and what remains marks the terms MAJOR, MINOR and PATCH, where the bold is doing real work. Released changelog sections older than 2.0.0 keep their punctuation. Their text generated the GitHub Release bodies at the time, and editing them now would leave the two disagreeing about a version nobody can change.
Contributor
Author
|
Reopened under a clearer name and rationale. |
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.
The documentation reads as machine-written, and the two things doing most of that work are em dashes
and boldface used as a paragraph header.
[2.0.0]onlyEach em dash is replaced with the punctuation the sentence wanted rather than by a blanket rule: a
colon where a list follows, a full stop between two independent clauses, commas around a genuine aside.
On the boldface.
STABILITY.mdhad nine paragraphs opening with a bolded sentence standing in for aheading. That is the same tell in another shape, and when every paragraph carries an emphasised line
none of them is emphasised. What survives marks
MAJOR,MINORandPATCH, where the bold separatesa defined term from its definition.
What is deliberately untouched. Changelog sections for versions before
2.0.0. Their text generatedthe GitHub Release bodies at the time, and rewriting them now would leave the two surfaces disagreeing
about a release nobody can re-cut. The
[2.0.0]section is fair game because its Release body isregenerated from this file.
The repository description loses its em dash too.
No behaviour changes and no code changes.
./gradlew buildgreen, audit At standard.Note for later:
nacode-studios-docscurrently says repository documentation "uses em dashes andtypographic punctuation freely". That guidance is what produced this, and it should probably change.