docs: examples and restatements syntax to content standardization guidelines

.env.example

@@ -1,7 +1,7 @@
 # rename this file to .env and supply the values listed below
-# also make sure they are available to the build tool (e.g. Netlify)
+# also make sure they are available to the build tool (e.g., Netlify)
 # warning: variables prefixed with NEXT_PUBLIC_ will be made available to client-side code
-# be careful not to expose sensitive data (e.g. your Algolia admin key)
+# be careful not to expose sensitive data (e.g., your Algolia admin key)
 
 # Algolia environment (app ID, search key and base search index name required for search)
 # You can use the following test keys provided by DocSearch for local development/testing:
@@ -35,12 +35,12 @@ NEXT_PUBLIC_MATOMO_SITE_ID=
 NEXT_PUBLIC_IS_PREVIEW_DEPLOY=false
 
 # Build pages only for the specified langs. Leave it empty to build all the langs
-# e.g. `en,fr` will only build English and French pages
+# e.g., `en,fr` will only build English and French pages
 # Note: always include `en` as it is the default lang of the site
 NEXT_PUBLIC_BUILD_LOCALES=
 
 # If resource constraints are being hit during builds, change LIMIT_CPUS to a
-# fixed number of CPUs (e.g. 2) to limit the demand during build time
+# fixed number of CPUs (e.g., 2) to limit the demand during build time
 LIMIT_CPUS=
 
 # Enables the bundle analyzer

.github/ISSUE_TEMPLATE/suggest_staking_product.yaml

@@ -187,17 +187,17 @@ body:
     id: staking_product_platform_support
     attributes:
       label: What platforms are supported?
-      description: ie. Linux, macOS, Windows, iOS, Android, etc
+      description: i.e., Linux, macOS, Windows, iOS, Android, etc
   - type: input
     id: staking_product_interface
     attributes:
       label: What user interfaces are supported?
-      description: ie. browser app, desktop app, mobile app, CLI app, etc
+      description: i.e., browser app, desktop app, mobile app, CLI app, etc
   - type: textarea
     id: staking_product_socials
     attributes:
       label: Social media links
-      description: List available social media links. ie. Discord, Twitter, Telegram, Reddit
+      description: List available social media links. i.e., Discord, Twitter, Telegram, Reddit
   - type: checkboxes
     id: staking_product_work_on
     attributes:

.github/ISSUE_TEMPLATE/suggest_wallet.yaml

@@ -55,7 +55,7 @@ body:
     id: wallet_url
     attributes:
       label: URL to the project
-      description: Please provide a URL (e.g. to the website of the wallet).
+      description: Please provide a URL (e.g., to the website of the wallet).
     validations:
       required: true
   - type: input
@@ -129,7 +129,7 @@ body:
     id: wallets_hardware
     attributes:
       label: Is it a hardware wallet?
-      description: How does it broadcast signed transactions (e.g. USB, Bluetooth, QR code)?
+      description: How does it broadcast signed transactions (e.g., USB, Bluetooth, QR code)?
     validations:
       required: true
   - type: markdown
@@ -194,7 +194,7 @@ body:
     id: wallet_scam_protection
     attributes:
       label: Scam protection?
-      description: Does the wallet employ any practices to warn users against potential scams (e.g. when interacting with suspicious accounts/contracts)?
+      description: Does the wallet employ any practices to warn users against potential scams (e.g., when interacting with suspicious accounts/contracts)?
     validations:
       required: true
   - type: markdown
@@ -205,7 +205,7 @@ body:
     id: wallet_dapp_support
     attributes:
       label: Does the wallet support connecting to Ethereum applications?
-      description: Please provide documentation for how users connect to applications. List examples (ie. WalletConnect, connect wallet to dapp directly, in wallet browser, etc.)
+      description: Please provide documentation for how users connect to applications. List examples (i.e., WalletConnect, connect wallet to dapp directly, in wallet browser, etc.)
     validations:
       required: true
   - type: dropdown
@@ -379,7 +379,7 @@ body:
     id: wallet_extra
     attributes:
       label: Does the wallet have any integrated tools not mentioned above?
-      description: Please provide any information about extra features this wallet has that we may have missed in the above criteria. (e.g. privacy features, transaction batching, etc).
+      description: Please provide any information about extra features this wallet has that we may have missed in the above criteria. (e.g., privacy features, transaction batching, etc).
   - type: checkboxes
     id: wallet_work_on
     attributes:

CODE_OF_CONDUCT.md

@@ -62,7 +62,7 @@ Examples of unacceptable behavior by participants include:
 
 Violations of the code of conduct will normally be visible to the community as we try to do everything in open, public channels, allowing community members to self-police.
 
-However, if something happens that you feel needs attention, you can raise it with someone who has a moderation role (e.g. discord guide) so that they can help investigate and execute the appropriate response.
+However, if something happens that you feel needs attention, you can raise it with someone who has a moderation role (e.g., discord guide) so that they can help investigate and execute the appropriate response.
 
 When reporting, please include as much detail as possible, including specific examples and timestamps. This will help to ensure a fair outcome.
 

README.md

@@ -135,7 +135,7 @@ pnpm dev
 - Open this directory in your favorite text editor / IDE, and see your changes live by visiting `localhost:3000` from your browser
 - Pro Tip:
   - Explore scripts within `package.json` for more build options
-  - Get **faster** production builds by building only one language. E.g. in your `.env` file, set `NEXT_PUBLIC_BUILD_LOCALES=en` to build the content only in English
+  - Get **faster** production builds by building only one language, e.g., in your `.env` file, set `NEXT_PUBLIC_BUILD_LOCALES=en` to build the content only in English
   - To build the site in other selected languages too, you need to set them in `NEXT_PUBLIC_BUILD_LOCALES`, eg: `NEXT_PUBLIC_BUILD_LOCALES=en,es` if you also want to build only English (required) and Spanish.
   - To build all languages, simply comment this line out with a hash mark, eg: `# NEXT_PUBLIC_BUILD_LOCALES=`
 
@@ -158,7 +158,7 @@ git push
 - After your changes are committed to your GitHub fork, submit a pull request (PR) to the `dev` branch of the `ethereum/ethereum-org-website` repo
 - In your PR description, reference the issue it resolves (see [linking a pull request to an issue using a keyword](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword))
   - ex. `Updates out of date content [Fixes #1234]`
-- Netlify (our hosting service for build previews) deploys all PRs to a publicly accessible preview URL, e.g.: ![Netlify deploy preview](public/images/preview-deploy.png)
+- Netlify (our hosting service for build previews) deploys all PRs to a publicly accessible preview URL, e.g.,: ![Netlify deploy preview](public/images/preview-deploy.png)
 - _Confirm that your Netlify preview deploy looks and functions as expected_
 - Why not say hi and draw attention to your PR in [our discord server](https://discord.gg/ethereum-org)?
 

docs/applying-storybook.md

@@ -52,11 +52,11 @@ type Story = StoryObj<typeof meta>;
 export const Basic: Story = {}
 ```
 
-- With the `title` option, we write this based on the groupings set by the Design System. Groupings are declared with forward slashes. (i.e. `Atoms / Form / Input`). See the Storybook docs for details on [Naming conventions](https://storybook.js.org/docs/7.0/react/writing-stories/naming-components-and-hierarchy)
+- With the `title` option, we write this based on the groupings set by the Design System. Groupings are declared with forward slashes. (i.e., `Atoms / Form / Input`). See the Storybook docs for details on [Naming conventions](https://storybook.js.org/docs/7.0/react/writing-stories/naming-components-and-hierarchy)
 - The `satisfies` TypeScript keyword is used with the `Meta` type for stricter type checking. This is particularly helpful to make sure required args are not missed. [Storybook Docs regarding `satisfies`](https://storybook.js.org/docs/writing-stories/typescript#using-satisfies-for-better-type-safety)
 - The use of `StoryObj` is to be able to typecheck the creation of a story as an object. This helps with prop inference.
 - We use `StoryObj<typeof meta>` in the event a required arg is provided in the `meta` object, to be applied to all stories in the file. This prevents type errors throwing at the story level for a required missing arg.
-- If the story does not need any args or any custom rendering, it should be left as an empty object. Otherwise, use the `render` option to explicitly write the rendering of the story: i.e. `render: () => <Component />`
+- If the story does not need any args or any custom rendering, it should be left as an empty object. Otherwise, use the `render` option to explicitly write the rendering of the story: i.e., `render: () => <Component />`
 
 Also, please view the Figma file for the [proposed structure for the Design System](https://www.figma.com/file/Ne3iAassyfAcJ0AlgqioAP/DS-to-storybook-structure?type=design&node-id=42%3A50&mode=design&t=RGkyouvTilzF42y0-1) to provide the correct groupings.
 

docs/best-practices.md

@@ -8,7 +8,7 @@ How to prepare your content for translation depends on whether you're working on
 
 **- MDX pages (`public/content/page/`)**
 
-Markdown will be translated as whole pages of content, so no specific action is required. Simply create a new folder within `public/content/` with the name of the page, then place an index markdown file (ie. `index.md`) within the new folder.
+Markdown will be translated as whole pages of content, so no specific action is required. Simply create a new folder within `public/content/` with the name of the page, then place an index markdown file (i.e., `index.md`) within the new folder.
 
 **- React component page**
 

docs/code-conventions.md

@@ -65,7 +65,7 @@ For the props type signature use the naming convention `<ComponentName>Props` to
 
 A positive side-effect to directly annotating the props object is for IDE intellisense where you can view the props when hovering over the component name to see it's signature.
 
-i.e. `const Component: ({ label, title, ...props }: ComponentProps) => React.JSX.Element`
+i.e., `const Component: ({ label, title, ...props }: ComponentProps) => React.JSX.Element`
 
 #### Use the type alias for props type
 

docs/ds-implementation.md

@@ -38,7 +38,7 @@ If you are implementing:
 
 ### 🧩 Base components
 
-*(components that already exist in the [shadcn/ui components list](https://ui.shadcn.com/docs/components), e.g. Button, Input, Alert)*
+*(components that already exist in the [shadcn/ui components list](https://ui.shadcn.com/docs/components), e.g., Button, Input, Alert)*
 
 * Do **not** create a new component file under `/ComponentA/index.tsx` unless additional or custom logic is required.
 * Extend or style base components in `src/components/ui`.
@@ -47,7 +47,7 @@ If you are implementing:
 
 ### 🧱 Custom components
 
-*(components not covered by shadcn/ui, e.g. PageHero)*
+*(components not covered by shadcn/ui, e.g., PageHero)*
 
 * Use base `ui` components whenever possible.
 * Keep the structure consistent with the DS and Figma specifications.

docs/event-tracking.md

@@ -35,7 +35,7 @@ It's helpful to ask yourself how the results of what we track and measure might
 
 # How to name events?
 
-Broadly, events should be grouped by specific topic (e.g. L2 page external links, selected bridge, selected cex).
+Broadly, events should be grouped by specific topic (e.g., L2 page external links, selected bridge, selected cex).
 
 ## Each event comprises 4 hierarchical values:
 

docs/review-process.md

@@ -30,7 +30,7 @@ Any new feature correlated with an approved issue is of medium priority. Similar
 
 ### Content
 
-Content PRs are considered medium-priority. Depending on their content, they can be very high-impact but also a high effort to go through the various stages of content review to ensure the content meets the standards we aim for. Content PRs can be broken into two categories: major content (e.g. a new page) and minor content changes (e.g. a new section to an existing page). Typo or grammar fixes are considered separately.
+Content PRs are considered medium-priority. Depending on their content, they can be very high-impact but also a high effort to go through the various stages of content review to ensure the content meets the standards we aim for. Content PRs can be broken into two categories: major content (e.g., a new page) and minor content changes (e.g., a new section to an existing page). Typo or grammar fixes are considered separately.
 
 **Timeline:** Major content should be merged within 30 days of opening. Minor content changes within 14 days of opening.
 

docs/site-search.md

@@ -20,7 +20,7 @@ Some important notes about the DocSearch config:
 - Selectors are used to specify what the crawler should look for when weighting content for the index.
 - CheerioAPI can be utilized within the crawler using the `$` selector to manipulate the DOM before indexing each page
 - Elements to be ignored are removed before indexing using the CheerioAPI library: `$('selector').remove()`. This includes `aside`, `nav`, `footer` and `style` elements.
-- While building pages, semantic naming with the aforementioned elements, i.e. `aside`, will ignore any content contained within. This is beneficial for content that is not directly related to the page content, such as callouts, banners, quiz content, or navigation elements.
+- While building pages, semantic naming with the aforementioned elements, i.e., `aside`, will ignore any content contained within. This is beneficial for content that is not directly related to the page content, such as callouts, banners, quiz content, or navigation elements.
 
 ## Resources
 

public/content/community/code-of-conduct/index.md

@@ -68,7 +68,7 @@ Examples of unacceptable behavior by participants include:
 
 Violations of the code of conduct will normally be visible to the community as we try to do everything in open, public channels, allowing community members to self-police.
 
-However, if something happens that you feel needs attention, you can raise it with someone who has a moderation role (e.g. discord guide) so that they can help investigate and execute the appropriate response.
+However, if something happens that you feel needs attention, you can raise it with someone who has a moderation role (e.g., discord guide) so that they can help investigate and execute the appropriate response.
 
 When reporting, please include as much detail as possible, including specific examples and timestamps. This will help to ensure a fair outcome.
 

public/content/community/events/organizing/index.md

@@ -55,7 +55,7 @@ By providing diverse opportunities for learning, collaboration, and growth, you
 
 Organizing a successful Ethereum conference or community event requires careful timing and consideration. The right moment depends on a variety of factors that contribute to the event's overall success.
 
-You should take into consideration community maturity, market conditions, whether you have a team, and whether there is a local scene (e.g. potential sponsors).
+You should take into consideration community maturity, market conditions, whether you have a team, and whether there is a local scene (e.g., potential sponsors).
 
 ### KYC — Know your community {#kyc-know-your-community}
 

public/content/community/research/index.md

@@ -57,7 +57,7 @@ The execution layer is concerned with executing transactions, running the [Ether
 
 - building out light client support;
 - researching gas limits;
-- and incorporating new data structures (e.g. Verkle Tries).
+- and incorporating new data structures (e.g., Verkle Tries).
 
 #### Background reading {#background-reading-1}
 
@@ -266,7 +266,7 @@ Validators use Ethereum's native asset (ether) as collateral against dishonest b
 
 ### Liquid staking and derivatives {#liquid-staking-and-derivatives}
 
-Liquid staking allows users with less than 32 ETH to receive staking yields by swapping ether for a token representing staked ether that can be used in DeFi. However, the incentives and market dynamics associated with liquid staking are still being discovered, as well as its effect on Ethereum's security (e.g. centralization risks).
+Liquid staking allows users with less than 32 ETH to receive staking yields by swapping ether for a token representing staked ether that can be used in DeFi. However, the incentives and market dynamics associated with liquid staking are still being discovered, as well as its effect on Ethereum's security (e.g., centralization risks).
 
 #### Background reading {#background-reading-12}
 

public/content/contributing/adding-layer-2s/index.md

@@ -78,7 +78,7 @@ _We do not consider other scaling solutions that don't use Ethereum for data ava
 
 **Links to dapps in the layer 2 ecosystem**
 
-- We want to be able to provide information on what users can expect to be able to do on this layer 2. (e.g. https://portal.arbitrum.io/)
+- We want to be able to provide information on what users can expect to be able to do on this layer 2. (e.g., https://portal.arbitrum.io/, https://www.optimism.io/apps)
 
 **Token contract lists**
 

public/content/contributing/adding-staking-products/index.md

@@ -57,7 +57,7 @@ Staking products or services submissions will be assessed by the following crite
 
 **What platforms are supported?**
 
-- i.e. Linux, macOS, Windows, iOS, Android
+- i.e., Linux, macOS, Windows, iOS, Android
 
 #### Software and smart contracts {#software-and-smart-contracts}
 
@@ -87,18 +87,18 @@ For any custom software or smart contracts involved:
 
 For software products related to node or client setup, management or migration:
 
-**Which consensus layer clients (i.e. Lighthouse, Teku, Nimbus, Prysm, Grandine) are supported?**
+**Which consensus layer clients (i.e., Lighthouse, Teku, Nimbus, Prysm, Grandine) are supported?**
 
 - Which clients are supported? Can the user choose?
 - This is used to determine the products "multi-client" score.
 
 #### Staking as a service {#staking-as-a-service}
 
-For [staking-as-a-service listings](/staking/saas/) (i.e. delegated node operation):
+For [staking-as-a-service listings](/staking/saas/) (i.e., delegated node operation):
 
 **What are the fees associated with using the service?**
 
-- What is the fee structure, e.g. is there a monthly fee for the service?
+- What is the fee structure, e.g., is there a monthly fee for the service?
 - Any additional staking requirements?
 
 **Are users required to sign-up for an account?**
@@ -123,7 +123,7 @@ For [pooled staking services](/staking/pools/):
 
 **What is the minimum ETH required to stake?**
 
-- e.g. 0.01 ETH
+- e.g., 0.01 ETH
 
 **What are the fees or staking requirements involved?**
 
@@ -151,7 +151,7 @@ For [pooled staking services](/staking/pools/):
 
 **What user interfaces are supported?**
 
-- i.e. Browser app, desktop app, mobile app, CLI
+- i.e., Browser app, desktop app, mobile app, CLI
 
 **For node tooling, does the software provide an easy way to switch between clients?**