docs: update based on prior convos (#52)

src/content/docs/content/global.mdx

@@ -13,7 +13,7 @@ This guide covers styles that are shared between all doc sites using the Starlig
 Styles should apply to all sites whenever possible; however, there could be a need for site-specific styles. If you can’t find what you’re looking for in this guide, check in a site-specific guide.
 
 - [Web Monetization](/content/webmonetization)
-- [Rafiki](/content/rafiki) (not started)
+- [Rafiki](/content/rafiki)
 - [Open Payments](/content/openpayments)
 - Payment Pointers (not started)
 - [Interledger](/content/interledger) (not started)
@@ -24,6 +24,10 @@ Break the rules.
 
 Ok, try not to, but the audience’s best interest should always come first. Deviations are OK if they help enhance the clarity of the doc.
 
+## Account servicing entity
+
+We're currently treating account servicing entity as an improper/common noun, meaning each letter should be in lowercase. ASE is an approved initialism.
+
 ## APIs/API's
 
 - Plural - APIs
@@ -150,9 +154,26 @@ https://moz.com/learn/seo/alt-text
   - All items start with a capital letter, or all start with lowercase.
 - If a list is introduced by a full sentence, end the sentence with the proper punctuation. If introduced with a sentence fragment, end with a colon.
 
-## See, View [link]
+## Please
+
+We're taking [Google's approach](https://developers.google.com/style/word-list#please): Don’t use please in the normal course of explaining how to use a product, even if you’re explaining a difficult task.
+
+## See
+
+Previously, we tried to be more inclusive by staying away from using *see* when referring to a link (e.g., *see XYZ for more information*).
+
+We've decided that it **is** OK to use *see*.
+
+The W3C uses *see* for link references within their [Accessibility, Usability, and Inclusion](https://www.w3.org/WAI/fundamentals/accessibility-usability-inclusion/) page. Similarly, Google uses it within their [Write inclusive documentation](https://developers.google.com/style/inclusive-documentation) page and their [word list](https://developers.google.com/style/word-list#see) indicates its OK to use when referring to links and cross-references.
+
+## SHA (secure hash algorithm)
+
+SHA is a common technical term that does not need to be defined before it's first use. 
+
+When an a/an article is needed, use **a**. 
 
-When possible, avoid using the words "see" and "view" when referencing a link. It’s a small thing, but some of our audience might use screen readers. The terms "visit", "review", and "refer to" might be acceptable substitutes.
+- A SHA-256 hash of the interaction is sent in the response. ✅
+- An SHA-256 has of the interaction is sent in the response. ❌
 
 ## Sidebar categories
 

src/content/docs/content/markdown.mdx

@@ -8,11 +8,11 @@ import { CodeBlock } from "@interledger/docs-design-system";
 
 Starlight supports the full range of [Markdown](https://daringfireball.net/projects/markdown/) syntax in `.md` files as well as frontmatter [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) to define metadata such as a title and description.
 
-Please be sure to check the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) or [Markdoc docs](https://markdoc.dev/docs/syntax) if using those file formats, as Markdown support and usage can differ.
+Be sure to check the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) or [Markdoc docs](https://markdoc.dev/docs/syntax) if using those file formats, as Markdown support and usage can differ.
 
 ## Frontmatter
 
-The `title` is a required field and if you create an `.md` or `.mdx` file without it in the content folder, the site will yell at you. Please check the full list of [frontmatter configuration](https://starlight.astro.build/reference/frontmatter/) for more fun options.
+The `title` is a required field and if you create an `.md` or `.mdx` file without it in the content folder, the site will yell at you. Check the full list of [frontmatter configuration](https://starlight.astro.build/reference/frontmatter/) for more fun options.
 
 ```md
 ---
@@ -64,7 +64,7 @@ You may want to further organise the img folder with subfolders if the project h
 
 ## Headings
 
-Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. If you need to modify this behavior for whatever reason, please consult the person responsible for documentation architecture.
+Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. If you need to modify this behavior for whatever reason, consult the person responsible for documentation architecture.
 
 ### Automatic heading anchor links
 
@@ -314,13 +314,13 @@ Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. Y
 ### Mermaid diagrams
 
 :::danger
-We no longer support mermaid diagrams using the markdown syntax. Instead, please use our custom [`Mermaid` component](/shared/mermaid).
+We no longer support mermaid diagrams using the markdown syntax. Instead, use our custom [`Mermaid` component](/shared/mermaid).
 :::
 
 ### Mathjax
 
 :::caution
-This component requires an extra dependency on [remark-math](https://github.com/remarkjs/remark-math/tree/main) and [rehype-mathjax](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax) and thus is not enabled by default on all projects. Please ping the person responsible for documentation architecture if your project doesn't render mathjax properly.
+This component requires an extra dependency on [remark-math](https://github.com/remarkjs/remark-math/tree/main) and [rehype-mathjax](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax) and thus is not enabled by default on all projects. Ping the person responsible for documentation architecture if your project doesn't render mathjax properly.
 :::
 
 $currencyAmount = \frac{value}{10^{assetScale}}$

src/content/docs/content/openpayments.mdx

@@ -26,7 +26,6 @@ pnpm start
 
 ### Common nouns
 
-- account servicing entity
 - payment pointer
 - wallet address
 

src/content/docs/content/rafiki.mdx

@@ -26,7 +26,21 @@ pnpm start
 ```
 </Card>
 
-## Custom table styles
+## Nouns
+
+### Common nouns
+* authorization server
+* resource server 
+
+## Spellings
+
+### backend/frontend 
+
+When writing about the backend/frontend services and packages in Rafiki, spell as shown. Don't hyphenate or add a space (e.g., back end). FWIW, this is how Microsoft, Google, and Cloudflare treat the terms in their docs.
+
+## Rafiki-specific styles
+
+### Custom table styles
 
 We've implemented a few different custom table styles specifically for Rafiki docs. These custom styles were developed because we were running into scrolling issues as well as column width issues, primarily when text was formatted as code.
 

src/content/docs/content/webmonetization.mdx

@@ -16,7 +16,6 @@ bun run start
 
 ### Common nouns
 
-- account servicing entity*
 - monetization `<link>` element
 - provider
 - receiver
@@ -31,7 +30,7 @@ bun run start
 - Rafiki
 - Web Monetization (always spell out, do not abbreviate as WM)
 
-## Account servicing entity*
+## Account servicing entity
 
 Don't use account servicing entity/ASE in the Web Monetization docs. Use wallet.
 

src/content/docs/index.mdx

@@ -49,7 +49,7 @@ import '/node_modules/@interledger/docs-design-system/src/styles/teal-theme
 
 ## Components
 
-Starlight provides some built-in components that are commonly used for documentation sites. Please refer to the [Starlight documentation](https://starlight.astro.build/guides/components#built-in-components) for detailed information on how to use them.
+Starlight provides some built-in components that are commonly used for documentation sites. Refer to the [Starlight documentation](https://starlight.astro.build/guides/components#built-in-components) for detailed information on how to use them.
 
 :::note
 The Starlight team releases new components from time to time. If you find a component in their doc that doesn't work with an Interledger doc site, we may need to upgrade our version of Starlight.
@@ -63,7 +63,7 @@ If you are using multiple shared components on a single page, you can import the
 import { CodeBlock, Disclosure } from "@interledger/docs-design-system";
 ```
 
-For more information about importing things in Javascript, please refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).
+For more information about importing things in Javascript, refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).
 
 ## Docs site building
 
@@ -131,7 +131,7 @@ const { title, description } = Astro.props;
 
 It had been possible to [override the default Starlight components](https://starlight.astro.build/guides/overriding-components/) since v0.11.0, and most of our documentation sites implement this for our site header. This is because the default search bar takes up too much space for our aesthetic liking. 乁 ⁠(⁠ ⁠•⁠_⁠•⁠ ⁠)⁠ ㄏ
 
-Although we have contemplated making this a shared component, each site header is different enough that we've decided to leave it up to each individual site to handle. Please consult the documentation for how this works.
+Although we have contemplated making this a shared component, each site header is different enough that we've decided to leave it up to each individual site to handle. Consult the documentation for how this works.
 
 We want to keep some other UI components that come with the default header, so those have to be imported like so:
 

src/content/docs/oppm/chunkedsnippet.mdx

@@ -3,7 +3,7 @@ title: ChunkedSnippet
 ---
 
 :::caution
-This component only exists in the [Open Payments repository](https://github.com/interledger/open-payments/tree/main/docs/src/components). Please raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
+This component only exists in the [Open Payments repository](https://github.com/interledger/open-payments/tree/main/docs/src/components). Raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
 :::
 
 This component allows you to display specially formatted code snippet files from a public GitHub repo within a page. 

src/content/docs/oppm/fullsnippet.mdx

@@ -3,7 +3,7 @@ title: FullSnippet
 ---
 
 :::caution
-This component only exists in the [Open Payments repository](https://github.com/interledger/open-payments/tree/main/docs/src/components). Please raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
+This component only exists in the [Open Payments repository](https://github.com/interledger/open-payments/tree/main/docs/src/components). Raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
 :::
 
 This component allows you to pull an entire file from a public Github repository to be displayed as code within a page.

src/content/docs/shared/linkout.mdx

@@ -49,8 +49,8 @@ or another opening tag after the start of `paragraph`
 
 ### With icon
 
-Please consult the <LinkOut href="https://openpayments.guide/">OpenPayments API</LinkOut> for more information.
+Consult the <LinkOut href="https://openpayments.guide/">OpenPayments API</LinkOut> for more information.
 
 ### Without icon
 
-Please consult the <LinkOut href="https://openpayments.guide/" withIcon={false}>OpenPayments API</LinkOut> for more information.
+Consult the <LinkOut href="https://openpayments.guide/" withIcon={false}>OpenPayments API</LinkOut> for more information.

src/content/docs/webm/browsercompat.mdx

@@ -3,7 +3,7 @@ title: BrowserCompat
 ---
 
 :::caution
-This component only exists in the [Web Monetization repository](https://github.com/WICG/webmonetization/tree/main/src/components/docs). Please raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
+This component only exists in the [Web Monetization repository](https://github.com/WICG/webmonetization/tree/main/src/components/docs). Raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
 :::
 
 This component generates a compatibility table based on the browser compatibility data passed into it. The key is to pass the component the correct data.

src/content/docs/webm/specification.mdx

@@ -3,7 +3,7 @@ title: Specification
 ---
 
 :::caution
-This component only exists in the [Web Monetization repository](https://github.com/WICG/webmonetization/tree/main/src/components/docs). Please raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
+This component only exists in the [Web Monetization repository](https://github.com/WICG/webmonetization/tree/main/src/components/docs). Raise [an issue](https://github.com/interledger/docs-design-system/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEATURE%5D+%3Ctitle%3E) if you feel it should be elevated into the shared library.
 :::
 
 This component displays a link to the relevant section of the [Web Monetization specification](https://webmonetization.org/specification/) within a table.