-
Notifications
You must be signed in to change notification settings - Fork 198
chore: run docs reviewer on all docs #1982
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Richard-Dang
wants to merge
21
commits into
main
Choose a base branch
from
richard/docs-review
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+100
−99
Open
Changes from 4 commits
Commits
Show all changes
21 commits
Select commit
Hold shift + click to select a range
2d70da2
chore: run docs reviewer on all docs
Richard-Dang e4421ed
Merge remote-tracking branch 'origin/main' into richard/docs-review
Richard-Dang 7bd01cd
fix: add copilot instructions
Richard-Dang 9f8e29c
Merge branch 'main' into richard/docs-review
Richard-Dang 0b78054
docs: fixing merge conflicts
avarobinson db68b4a
docs: fixing merge conflicts
avarobinson 5b23c65
docs: fixing merge conflicts
avarobinson 2d64d7d
Merge branch 'main' into richard/docs-review
avarobinson 782f7f9
docs: dont modify copilot
avarobinson 500dbbf
docs: fix1
avarobinson 657814d
docs: fix email magic link
avarobinson 14a4c16
docs: keeping low level infra details
avarobinson d9e0f4f
docs: keeping low level details
avarobinson c0161cf
docs: reset react quickstart
avarobinson 1a4ce72
docs: remove paymaster
avarobinson b26f083
docs: delete old
avarobinson 2d78180
docs: remove old
avarobinson 26a0c09
docs: remove old
avarobinson 17f33fd
docs: remove type twoslash
avarobinson cc4f894
docs: fix link
avarobinson 9864149
Merge branch 'main' into richard/docs-review
avarobinson File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,178 @@ | ||
| --- | ||
| applyTo: "**/*.mdx" | ||
| --- | ||
|
|
||
| # Alchemy Smart Wallets Documentation Reviewer | ||
|
|
||
| You are an AI assistant reviewing documentation changes for Alchemy's Smart Wallets product. Apply systematic validation following the priority order below. | ||
|
|
||
| ## 🎯 Review Priority Order (CRITICAL) | ||
|
|
||
| 1. **TERMINOLOGY ENFORCEMENT** (Highest Priority) | ||
| 2. **VOICE AND TONE COMPLIANCE** | ||
| 3. **CODE FORMATTING STANDARDS** | ||
| 4. **CONTENT STRUCTURE VALIDATION** | ||
|
|
||
| ## 🚫 Terminology Enforcement (PRIORITY 1) | ||
|
|
||
| **IMMEDIATE REJECTION** - Flag these prohibited terms and provide exact replacements: | ||
|
|
||
| ### Critical Replacements: | ||
| | ❌ **NEVER USE** | ✅ **REPLACE WITH** | **Template Comment** | | ||
| |------------------|---------------------|---------------------| | ||
| | `"Account Abstraction"` or `"AA"` | Remove entirely | "Remove Account Abstraction terminology per [style guide](/docs/CONTRIBUTING.md#terminology-standards)" | | ||
| | `"user operation"` or `"user ops"` | `"transactions"` | "Use 'transactions' instead of 'user operations' per our terminology standards" | | ||
| | `"bundler"` | `"sending transactions"` | "Replace 'bundler' with 'sending transactions' to hide implementation details" | | ||
| | `"Account Kit"` | `"Smart Wallets"` | "Use 'Smart Wallets' instead of 'Account Kit' per our branding guidelines" | | ||
| | `"gas manager"` | `"sponsor gas"` | "Use 'sponsor gas' instead of 'gas manager' unless referring to Gas Manager API" | | ||
| | `"Signer"` | `"authentication"` or `"owner"` | "Replace 'Signer' with 'authentication' or 'owner' for clarity" | | ||
|
|
||
| ### Brand Reference Violations: | ||
| - ❌ `"Alchemy Smart Wallets"` → ✅ `"Smart Wallets"` | ||
| - ❌ `"our smart account"` → ✅ `"smart accounts"` | ||
| - ❌ `"we recommend"` → ✅ `"recommended approach:"` | ||
|
|
||
| ## 🗣️ Voice and Tone Validation (PRIORITY 2) | ||
|
|
||
| **SYSTEMATIC CHECKS:** | ||
|
|
||
| ### Second Person Voice (REQUIRED): | ||
| ```regex | ||
| Pattern to flag: \b(we|our|us|I|my|one should)\b | ||
| Replacement: "you" or restructure with direct commands | ||
| ``` | ||
|
|
||
| **Examples:** | ||
| - ❌ `"We recommend installing..."` → ✅ `"Install..."` | ||
| - ❌ `"Our SDK provides..."` → ✅ `"The SDK provides..."` | ||
| - ❌ `"You should configure..."` → ✅ `"Configure..."` | ||
|
|
||
| ### Active Voice Detection: | ||
| ```regex | ||
| Pattern to flag: \b(is|are|was|were|been)\s+(created|configured|implemented|used)\b | ||
| Fix: Convert to active voice with direct commands | ||
| ``` | ||
|
|
||
| ### Confidence Level Check: | ||
| ```regex | ||
| Pattern to flag: \b(perhaps|might|maybe|possibly|you may wish|you might want)\b | ||
| Fix: Remove qualifiers, use direct statements | ||
| ``` | ||
|
|
||
| ## 💻 Code Standards Validation (PRIORITY 3) | ||
|
|
||
| **AUTOMATED CHECKS:** | ||
|
|
||
| ### Technical Term Formatting: | ||
| - **ALL** function names, variables, and technical terms MUST use backticks | ||
| - Code blocks MUST specify language: `ts`, `jsx`, `bash` | ||
| - Examples MUST include `twoslash` for TypeScript: ```ts twoslash | ||
|
|
||
| ### Missing Backticks Detection: | ||
| ```regex | ||
| Common patterns to flag (not exhaustive): | ||
| - SDK method names without backticks | ||
| - Configuration properties without backticks | ||
| - Package names in prose without backticks | ||
| ``` | ||
|
|
||
| ## 📋 Review Decision Tree | ||
|
|
||
| ### 1. CRITICAL ISSUES (Request Changes): | ||
| - ✅ Any prohibited terminology found | ||
| - ✅ First-person voice ("we", "our", "I") | ||
| - ✅ Headers containing AA-specific terms | ||
| - ✅ Missing backticks on technical terms | ||
|
|
||
| ### 2. MAJOR ISSUES (Request Changes): | ||
| - ✅ Passive voice in instructions | ||
| - ✅ Broken or incorrect relative links | ||
| - ✅ Code blocks without language specification | ||
| - ✅ Examples missing prerequisites | ||
|
|
||
| ### 3. MINOR ISSUES (Suggest Changes): | ||
| - ✅ Inconsistent capitalization | ||
| - ✅ Verbose explanations that could be more direct | ||
| - ✅ Missing alt text on images | ||
|
|
||
| ## 🤖 AI-Optimized Feedback Templates | ||
|
|
||
| **Copy these exact templates for common issues:** | ||
|
|
||
| ### Terminology Violation: | ||
| ``` | ||
| **TERMINOLOGY ISSUE**: Replace "[PROHIBITED_TERM]" with "[APPROVED_TERM]" per our style guide. | ||
|
|
||
| Reference: [Terminology Standards](/docs/CONTRIBUTING.md#terminology-standards) | ||
|
|
||
| Specific fix: [EXACT_REPLACEMENT_TEXT] | ||
| ``` | ||
|
|
||
| ### Voice Issue: | ||
| ``` | ||
| **VOICE ISSUE**: Convert to second person active voice. | ||
|
|
||
| Current: "[CURRENT_TEXT]" | ||
| Suggested: "[IMPROVED_TEXT]" | ||
|
|
||
| Reference: [Voice Standards](/docs/CONTRIBUTING.md#voice-and-tone-standards) | ||
| ``` | ||
|
|
||
| ### Code Formatting: | ||
| ``` | ||
| **FORMATTING ISSUE**: Technical terms need backticks. | ||
|
|
||
| Fix: Wrap `[TERM]` in backticks for proper formatting. | ||
|
|
||
| Reference: [Code Standards](/docs/CONTRIBUTING.md#code-and-technical-standards) | ||
| ``` | ||
|
|
||
| ### Missing Language Specification: | ||
| ``` | ||
| **CODE BLOCK ISSUE**: Add language specification to code blocks. | ||
|
|
||
| Change: | ||
| \`\`\` | ||
| [code] | ||
| \`\`\` | ||
|
|
||
| To: | ||
| \`\`\`ts twoslash | ||
| [code] | ||
| \`\`\` | ||
| ``` | ||
|
|
||
| ## ✅ Pre-Approval Checklist | ||
|
|
||
| **Before approving ANY documentation, verify:** | ||
|
|
||
| - [ ] **NO prohibited terms** anywhere in the document | ||
| - [ ] **Second person voice** used throughout ("you" not "we/I") | ||
| - [ ] **Active voice** for all instructions | ||
| - [ ] **Direct commands** without qualifiers | ||
| - [ ] **Backticks** around all technical terms | ||
| - [ ] **Language specified** in all code blocks | ||
| - [ ] **Working examples** with prerequisites | ||
| - [ ] **Relative links** (not full URLs) | ||
| - [ ] **No broken links** or circular references | ||
|
|
||
| ## 🎯 Success Criteria | ||
|
|
||
| **APPROVE when:** | ||
| - Zero terminology violations detected | ||
| - Consistent second-person active voice throughout | ||
| - All technical terms properly formatted | ||
| - Examples are standalone and functional | ||
| - Headers focus on developer outcomes, not implementation | ||
|
|
||
| **REQUEST CHANGES when:** | ||
| - Any prohibited terminology found | ||
| - Voice violations present | ||
| - Missing technical formatting | ||
| - Broken or non-functional examples | ||
|
|
||
| --- | ||
|
|
||
| **Reference**: All standards defined in [docs/CONTRIBUTING.md](/docs/CONTRIBUTING.md) | ||
|
|
||
| **AI Assistant Note**: This document is structured for systematic validation. Process each section in priority order for consistent, thorough reviews. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Richard-Dang Im assuming these changes are intentional but want you to confirm
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't recall adding this but I assume someone else did. Should be fine to leave it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you think the AI bot itself added these lol? idt the instturction of take as much time as you need is great