docs: add-hard-stops-styling #16528
docs: add-hard-stops-styling #16528
Conversation
pete-vielhaber
requested review from
corwintines,
minimalsm,
pettinarip and
wackerow
as code owners
✅ Deploy Preview for ethereumorg ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
bot
added
content 🖋️
|
Thanks for the clean up @pete-vielhaber! ("full" stop to my understanding, no?) I see a bunch of conflicts, any chance you could help clean those up before I go through all these?? 🙏 (Small housekeeping note as well... Smaller chunked PR's tend to be much easier to review vs those touching 261 files 😅 Not a huge deal, but just noting this for future efforts, a few files at a time speeds up review and minimizes risk of conflicts forming) |
I've heard both full and hard stops in professional settings—honestly not sure which is "proper." Sure I can try and resolve any conflicts. And yes, in hindsight, I should have broken this into smaller chunks—noted for the future 🙏 |
|
@wackerow cleaned up conflicts—should be good to go 👍 Apologies again for the huge PR. Most changes are limited to one comma after i.e. or e.g. per doc (a few have 2-3)—except the style guide page. Should make for a relatively quick review 🙏 |
There was a problem hiding this comment.
Thanks @pete-vielhaber! Left a comment below about the content-standardization updates
|
|
||
| By adhering to these guidelines, we create a unified approach to presenting dates, fostering clarity and comprehension throughout Ethereum documentation. | ||
|
|
||
| ### Hard stops (i.e., and e.g.,) {#hard-stops} |
There was a problem hiding this comment.
Still not quite convinced that "hard stop" is correct usage, but regardless, this isn't really about periods/full stops, it's about the usage of e.g. and i.e., including which is appropriate to use in different circumstances (not interchangeable), and correct punctuation, including both the use of periods and the comma following.
https://www.merriam-webster.com/grammar/ie-vs-eg-abbreviation-meaning-usage-difference
I really like the clarity Merriam-Webster brings here, noting the definitions of each:
I.e. stands for the Latin id est, or 'that is,' and is used to introduce a word or phrase that restates what has been said previously.
E.g. means “for example.” (It stands for exempli gratia in Latin.) It is used in much the same ways as 'for example,' coming before an item or list of items.
I would update the header according to focus less on the the punctuation alone and more on the general usage of these two indicators.
There was a problem hiding this comment.
For the sake of not expanding the scope of this PR, I would not go through and change "examples" that use "i.e.," to "e.g.,", nor restatements from "e.g.," to "i.e.," although separately it would be nice to also make those adjustments for further polishing.
There was a problem hiding this comment.
Less important, but this is generally lower priority and would consider moving this lower in the page, perhaps adjacent to the section ### Hyphen (-), en dash (–), and em dash (—): usage guide {#dash-usage-guide}
There was a problem hiding this comment.
Consider:
| ### Hard stops (i.e., and e.g.,) {#hard-stops} | |
| ### Examples (e.g.) and restatements (i.e.): usage guide {#example-restatements} |
And a nice-to-have would be a brief summary of the definition of these terms, guiding the two use cases.
2 participants
Added hard stops to style guide; thoroughly went through entire repo and replaced instances of
ie.eg.i.e.ande.g.withi.e.,ande.g.,Related to thisDescription
Related Issue
From previous Issue/PR, suggestion was to add to style guide and replace throughout documentation.