Merge pull request #16528 from pete-vielhaber/hardstops

docs: examples and restatements syntax to content standardization guidelines

Author: wackerow

.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: