Doc standardization

[JSON]

Some standardization edits, given diff writers between docs.

Primary updates:

• Abbreviations Eth 2.0/Eth2.0/eth2.0/ETH 2.0 standardized to “Eth 2.0” (ETH when referring to ether is left as is; Ethereum→Eth, ether→ETH) (Ethereum 2.0 when spelled out, left as is; any code like Eth2Genesis or the spec name eth2.0-specs, ofc also left as is)
• If a page has a ToC, parallel formatting as the specs/core docs’ ToCs
• ie/ie./i.e./i.e., + eg/eg./e.g./e.g., standardized to i.e.,/e.g., (chicago manual of style/ap stylebook use both periods + a comma) (didn’t touch the ones in code snippets)
• Replacing “:” with “-” in 1_custody-game.md’s Terminology section to match 0_beacon-chain.md’s
• Capitalization when referring to a specific phase (was about half and half beforehand)

Misc.:

• Adding the title to the “Merkle proof formats” doc; was missing
• Adding the RFC 2119 link when referenced
• Adding the C++ SSZ maintainer
• Updating links to the now deprecated ethereum/eth2.0-tests repo to the new ethereum/eth2.0-spec-tests repo
• Grammar

[JustinDrake]

Thank for this. I mostly care for consistency but will voice some personal bikesheding nonetheless 😂

1. We are not consistent on capitalisation of section headers. My preference would be to avoid capitalisation except for the first word. So "Table of Contents" => "Table of contents", "Message Structure" => "Message structure", etc.
2. I dislike the dash - in the terminology sections. The the em-dash — or the colon : feel more appropriate.
3. While eg feels wrong, e.g., feels heavy. What about the common e.g.?
4. Have you run all the text through a spell-checker?
5. "To learn more about sharding and Ethereum 2.0 (Serenity)" is inconsistent with your Eth 2.0 normalisation. Suggest removing this single instance of "Serenity" (it's somewhat arcane internal lingo) and favouring the self-explanatory "Eth 2.0".
6. I suggest avoiding abbreviations throughout such as "can be up to 64 bits (incl.)"
7. Have you checked for consistency on American spelling versus English spelling?
8. Not a fan of the double colon in "Value: can be any of:"
9. Not a fan of the all-caps "NOTICE".
10. Not a fan of the double dash in titles such as "Ethereum 2.0 Phase 0 -- The Beacon Chain". The em-dash is usual. On that note, would be nice to normalise capitalisation and "Ethereum 2.0" here as well. Would also be nice to normalise with other titles such as "Eth 2.0 Networking Spec - RPC Interface"
11. Suggest using lower case for "beacon chain" in various places.

[JSON]

@JustinDrake

Can I go forward with making all of those requested changes now?

& For #10, are you saying to go with the full spelling "Ethereum 2.0" + em-dash in titles, like:

Ethereum 2.0 Networking Spec — RPC Interface

Thank you

[JustinDrake]

For #10, are you saying to go with the full spelling "Ethereum 2.0" + em-dash in titles, like "Ethereum 2.0 Networking Spec — RPC Interface"

My suggestion would be something like "Ethereum 2.0 networking spec—RPC interface". No spaces between em-dash, avoid upper case except first word. Then again this is just my personal preference—mostly care for consistency.

[JSON]

@JustinDrake

1. Done
2. Done (used em-dashes; they look the same as en's on the editing page, but they're em's)
3. Done
4. Done
5. Done
6. Don't know if the author meant included/inclusive (and of what exactly?) there, so can't make the edit. Found a "PR" that I changed to pull request. Other abbreviations were pretty basic, so I let them be (examples: spec/s, misc, max). Would you like those in full too or are they fine?
7. Done—searched for British suffixes, found 2 and edited. Didn't catch anything else
8. Done—made it stylized as:

Value can be either:

• an unsigned integer number, can be up to 64 bits (incl.)
• a hexadecimal string, prefixed with 0x

9. Done
10. Waiting on consensus from others or a go-ahead from you
11. The only capitalized "beacon chain" spots remaining are in reference to the title of the beacon chain spec itself, where it is now capitalized (so will act on this in accordance to Update Variable Naming in Crosslink Rewards #10)

👍

[hwwhww]

@JSON Thank you so much for making this! 👍

Personal preference here:

1. I have OCD of e.g.,/i.e., too so I’d support e.g.,/i.e.,...
2. IMHO I still like using “Serenity” in somewhere to point out that Ethereum 2.0 is part of Ethereum early vision and plan. :)

[JSON]

@hwwhww @JustinDrake

#2 = Done. Since it's the first mention, I agree a full spell out + (Serenity) is optimal.

All that remains is a decision either way on ie/eg (this PR currently makes them all i.e./e.g. no comma) and a decision regarding title stylization (this PR currently leaves them as is). If no one wants to be declarative rn, this PR is ready to be merged as is, and I can do another scan for discrepancies in June for the Phase 0 spec freeze. Lmk

[djrtwo]

I say we merge as is

[JustinDrake]

I say we merge as is

Merged! Merging this quickly before merge conflicts make it impossible to work with. Happy to review a second pass :)