diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md new file mode 100644 index 000000000..a3a086cb0 --- /dev/null +++ b/.claude/commands/audit-doc.md @@ -0,0 +1,325 @@ +You are tasked with auditing documentation for compliance with pgflow guidelines, Diataxis framework, and identifying quality issues. + +## Context + +Documentation root: `pkgs/website/src/content/docs/` + +Target for audit: + +$ARGUMENTS + + +## Process + +### Step 1: Identify Scope + +**If specific file provided:** +- Audit that single file + +**If directory provided:** +- Audit all .mdx files in that directory + +**If "all" or no argument:** +- Ask user to confirm scope (this could be large) +- Suggest starting with specific section + +Present scope and WAIT for confirmation. + +### Step 2: Perform Comprehensive Audit + +For each file, check these categories: + +## Audit Categories + +### 1. DIATAXIS COMPLIANCE (Critical) + +Determine the file's location and intended type: +- `get-started/`, `tutorials/` → **Tutorial** +- `develop/`, `operate/` → **How-to Guide** +- `concepts/`, `comparisons/` → **Explanation** +- `reference/` → **Reference** + +**Check for violations:** + +**Tutorial violations:** +- [ ] Contains explanatory content that should be in concepts +- [ ] Includes reference material (API specs, option tables) +- [ ] Has branching "if/else" scenarios (tutorials should be linear) +- [ ] Lacks step-by-step structure +- [ ] Missing expected outcomes for steps + +**How-to violations:** +- [ ] Teaching basics from scratch (should assume knowledge) +- [ ] Contains conceptual explanations (should link to concepts) +- [ ] Not problem-focused +- [ ] Includes reference tables + +**Explanation violations:** +- [ ] Contains step-by-step instructions +- [ ] Has code examples meant to be followed +- [ ] Uses directive language ("Now do this...") +- [ ] Includes how-to content + +**Reference violations:** +- [ ] Contains explanations of concepts +- [ ] Has step-by-step examples +- [ ] Uses prescriptive language ("you should...") +- [ ] Missing specifications (incomplete option list) + +### 2. STYLE COMPLIANCE + +**Character issues:** +- [ ] Em-dashes (—) instead of hyphens (-) +- [ ] Curly quotes ("") instead of straight ("") +- [ ] Curly apostrophes (') instead of straight (') +- [ ] Ellipsis (…) instead of three periods (...) +- [ ] Non-breaking spaces + +**Naming convention:** +- [ ] "PgFlow", "pgFlow", "PGFlow" (should be "pgflow") +- [ ] Exception: "Pgflow" in class names is okay + +**Voice/perspective:** +- [ ] Uses "we", "our" in technical descriptions +- [ ] Uses "let's" unnecessarily +- [ ] Inconsistent use of "you" + +**Links:** +- [ ] Missing trailing slashes on internal links +- [ ] Relative paths instead of absolute +- [ ] "Click here" or non-descriptive link text + +### 3. STRUCTURAL ISSUES + +**Frontmatter:** +- [ ] Missing title +- [ ] Missing description +- [ ] Description too long (>100 chars) + +**Content structure:** +- [ ] Heading hierarchy jumps (H2 → H4) +- [ ] Inconsistent heading style +- [ ] Missing prerequisites (for tutorials/how-tos) +- [ ] No "Next Steps" section (for tutorials) +- [ ] No "Learn More" section (for how-tos) + +**Code examples:** +- [ ] Missing title attributes +- [ ] No highlighting of important lines +- [ ] Commands without frame="none" +- [ ] Missing context before code blocks +- [ ] Examples too long or too complex + +**Callouts/Asides:** +- [ ] More than 3 Asides (too many) +- [ ] Misuse of types (using "note" for warnings) +- [ ] Nested complex content in Asides + +### 4. CONTENT QUALITY + +**Clarity:** +- [ ] Verbose or redundant explanations +- [ ] Jargon without definition +- [ ] Unclear instructions +- [ ] Ambiguous references ("this", "it" without clear antecedent) + +**Completeness:** +- [ ] Missing code examples where needed +- [ ] Incomplete examples +- [ ] Missing prerequisites +- [ ] No success criteria + +**Accuracy:** +- [ ] Outdated information +- [ ] Incorrect commands or code +- [ ] Broken links +- [ ] References to non-existent files + +**Cross-references:** +- [ ] Missing links to related content +- [ ] Links to wrong content type +- [ ] Dead-end pages (no onward navigation) + +### 5. LENGTH AND DEPTH + +Check document length: +- Short: <100 lines +- Medium: 100-200 lines +- Long: 200-300 lines +- Very long: >300 lines + +**Issues:** +- [ ] Very long documents (>300 lines) - suggest splitting +- [ ] Reference pages that are too long - should be modular +- [ ] Tutorial steps that are too long - suggest breaking up + +## Audit Report Format + +Present findings in this structured format: + +```markdown +# Audit Report: [filename] + +**Location:** pkgs/website/src/content/docs/[path] +**Intended Type:** [Tutorial/How-to/Explanation/Reference] +**Length:** [count] lines ([Short/Medium/Long/Very Long]) + +## 🔴 CRITICAL ISSUES (Fix First) + +### Diataxis Violations +[List any mixed content or misplaced content] + +### Broken Functionality +[Broken links, incorrect code, etc.] + +## 🟡 IMPORTANT ISSUES (Fix Soon) + +### Style Violations +- Character issues: [count] +- Naming violations: [count] +- Voice issues: [count] + +### Structural Problems +[Missing sections, heading issues, etc.] + +## 🟢 IMPROVEMENTS (Nice to Have) + +### Content Quality +[Verbosity, clarity, completeness] + +### Cross-References +[Missing links, navigation improvements] + +## SUMMARY + +**Overall Assessment:** [Excellent/Good/Needs Work/Major Issues] + +**Priority Actions:** +1. [Highest priority fix] +2. [Second priority fix] +3. [Third priority fix] + +**Suggested Commands:** +- [Command to run for quick fixes, e.g., `/fix-doc-style`] +- [Command for improvements, e.g., `/edit-doc`] +- [Command if needs splitting, e.g., `/split-doc` (future)] +``` + +### Step 3: Provide Specific Examples + +For each issue found, provide: +- Line number or section where issue occurs +- Example of the violation +- Suggested fix + +Example: +```markdown +### Voice Violation (Line 42) +**Found:** +> "Let's create our first flow" + +**Suggested:** +> "Create your first flow" +``` + +### Step 4: Batch Audit Summary + +If auditing multiple files, provide aggregate report: + +```markdown +# Batch Audit Summary + +**Files Audited:** [count] + +## Issue Distribution + +**Critical Issues:** [count] files +- Diataxis violations: [count] +- Broken links: [count] + +**Style Issues:** [count] files +- Character issues: [count] +- Voice issues: [count] + +**Content Quality:** [count] files need improvement + +## Files Needing Immediate Attention + +1. **[filename1]** - [Critical issue summary] +2. **[filename2]** - [Critical issue summary] +... + +## Files That Are Excellent +[List files with no issues - positive reinforcement!] + +## Recommended Actions + +1. Run `/fix-doc-style` on these files: [list] +2. Run `/edit-doc` on these files: [list] +3. Consider moving these files: [list with suggestions] +4. Consider splitting these files: [list] +``` + +## Quick Audit Mode + +If user requests "quick audit", perform faster check: +- Diataxis compliance only +- Critical style issues only (characters, naming) +- No detailed content quality review + +Present simplified report focusing on must-fix issues. + +## Deep Audit Mode + +If user requests "deep audit", perform comprehensive review: +- All categories above +- Read entire document carefully +- Check every code example +- Verify all links +- Assess readability and flow +- Suggest specific improvements + +May take longer but provides thorough analysis. + +## Comparison to Best Practices + +Reference these as exemplars: +- **Good tutorial:** `/get-started/flows/create-flow.mdx` +- **Good how-to:** `/operate/deploy/deploy-first-flow.mdx` +- **Good explanation:** `/concepts/architecture/how-pgflow-works.mdx` +- **Good reference:** (none fully compliant yet, use standards above) + +When auditing, compare structure and style to relevant exemplar. + +## Important Reminders + +- **Be specific** - Provide line numbers and examples +- **Be constructive** - Suggest fixes, not just criticism +- **Prioritize** - Critical issues first +- **Be comprehensive** - Check all categories +- **Be helpful** - Suggest which commands to run next + +## Special Cases + +**If file has many issues:** +- Group similar issues together +- Prioritize clearly +- May suggest complete rewrite vs. incremental fixes + +**If file is excellent:** +- Say so! Positive feedback is valuable +- Note what it does well +- Suggest as exemplar for similar docs + +**If unclear about intended content type:** +- Note the ambiguity +- Suggest clarifying or splitting +- Ask user for intent + +## Output + +Present comprehensive audit report using format above. + +For batch audits, provide both aggregate summary and per-file details. + +Suggest concrete next steps and commands to run. diff --git a/.claude/commands/create-doc.md b/.claude/commands/create-doc.md new file mode 100644 index 000000000..25aa81285 --- /dev/null +++ b/.claude/commands/create-doc.md @@ -0,0 +1,219 @@ +You are tasked with creating new documentation following pgflow's guidelines, Diataxis framework, and style conventions. + +## Context + +Project documentation location: `pkgs/website/src/content/docs/` + +Current directory structure: + +!`tree pkgs/website/src/content/docs/ -L 2 -d` + + +User request: + +$ARGUMENTS + + +## Process + +### Step 1: Determine Content Type (Diataxis) + +Analyze the user's request and determine which Diataxis category this document belongs to: + +**TUTORIALS** (Learning-oriented) - get-started/, tutorials/ +- First-time learning experience +- Step-by-step with expected outcomes +- Complete working examples +- "Create your first X" + +**HOW-TO GUIDES** (Problem-oriented) - develop/, operate/ +- Solving specific problems +- Assumes basic knowledge +- Practical, real-world scenarios +- "How to do X" + +**EXPLANATIONS** (Understanding-oriented) - concepts/, comparisons/ +- Building mental models +- Why and how it works +- Design decisions and tradeoffs +- No step-by-step instructions + +**REFERENCE** (Information-oriented) - reference/ +- Dry, factual specifications +- API signatures, options, types +- Tables and lists +- No explanations or examples + +Present your analysis to the user: +``` +Content Type: [CATEGORY] +Reasoning: [Why this category] +Suggested Location: pkgs/website/src/content/docs/[path]/[filename].mdx +``` + +WAIT for user confirmation or correction. + +### Step 2: Create Document Structure + +Based on the confirmed content type, create a document following these patterns: + +**For TUTORIALS:** +```markdown +--- +title: [Clear, action-oriented title] +description: [One-line description] +sidebar: + order: [number] +--- + +import { Aside, Steps } from '@astrojs/starlight/components'; + +[1-2 sentence introduction] + + + +## 1. [First Step] + +[Brief explanation] + +[Code example with frame="none" for commands] + +[Expected outcome] + +## 2. [Second Step] + +... + +## Next Steps + +[Links to related content using LinkCard] +``` + +**For HOW-TO GUIDES:** +```markdown +--- +title: [Problem-focused title] +description: [One-line description] +--- + +import { Aside, LinkCard } from '@astrojs/starlight/components'; + +[Problem statement - what this solves] + +## Solution + +[Direct instructions] + +[Code examples with highlighting] + +## Learn More + +[Links to related concepts and tutorials] +``` + +**For EXPLANATIONS:** +```markdown +--- +title: [Concept name] +description: [One-line description] +--- + +[Conceptual overview] + +## [Major Concept 1] + +[Explanation with diagrams if helpful] + +## [Major Concept 2] + +... + +## Summary + +[Recap key points] +``` + +**For REFERENCE:** +```markdown +--- +title: [API/Config name] +description: [One-line description] +--- + +[Minimal introduction] + +## [Section Name] + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| ... | ... | ... | ... | + +[Tables and lists only, no examples] +``` + +### Step 3: Apply Style Guidelines + +Ensure the document follows ALL these rules: + +**Character Guidelines:** +- Use straight quotes ("" '') NOT curly quotes +- Use hyphens (-) NOT em-dashes (—) +- Use straight apostrophes (') NOT curly apostrophes (') +- Use three periods (...) NOT ellipsis (…) +- Use regular spaces NOT non-breaking spaces + +**Voice and Perspective:** +- Use impersonal language for technical descriptions ("pgflow does X") +- Use "you" ONLY when directly instructing the reader +- NEVER use "we", "our", "let's" in technical descriptions +- Exception: "you" is okay in tutorials + +**Naming Convention:** +- Always lowercase: "pgflow" (NEVER PgFlow, pgFlow, PGFlow) +- Exception: PascalCase in class names (Pgflow) + +**Code Examples:** +- Use `frame="none"` for bash commands +- Add title attribute for context: `title="filename.ts"` +- Highlight important lines: `{1-3,5}` or `"highlightedTerm"` +- Include TypeScript type annotations +- Keep examples focused and concise + +**Links:** +- Always use trailing slashes: `/path/to/page/` +- Use absolute paths for internal links +- Use descriptive link text, not "click here" + +**Frontmatter:** +- Always include title and description +- Use sidebar.order for positioning if needed +- Keep descriptions concise (one line) + +### Step 4: Write the Document + +Create the complete document following all guidelines above. + +Present the document to the user for review. + +### Step 5: Create the File + +Once approved, write the file to the determined location. + +## Important Reminders + +- **Single purpose**: One content type per document +- **No mixed content**: Don't mix tutorial + explanation + reference +- **Cross-reference**: Link to related content instead of duplicating +- **MVP mindset**: Focus on core value, avoid over-complexity +- **Code examples**: Always real-world, working examples +- **Diataxis compliance**: Strict adherence to content type patterns + +## Output + +Write to: `pkgs/website/src/content/docs/[determined-path]` + +Confirm file creation and suggest any related updates needed (navigation, redirects, etc.) diff --git a/.claude/commands/edit-doc.md b/.claude/commands/edit-doc.md new file mode 100644 index 000000000..d9144dfe2 --- /dev/null +++ b/.claude/commands/edit-doc.md @@ -0,0 +1,224 @@ +You are tasked with improving existing documentation by enhancing clarity, fixing issues, and maintaining consistency with pgflow's style guidelines. + +## Context + +Documentation root: `pkgs/website/src/content/docs/` + +User request: + +$ARGUMENTS + + +## Process + +### Step 1: Identify Target Document + +Based on the user's request, determine which document(s) to edit. + +**If path provided explicitly:** +- Confirm the file exists +- Read the file + +**If description provided:** +- Search for relevant files using grep or glob +- Present matches to user in a/b/c format +- WAIT for user selection + +### Step 2: Read and Analyze Current State + +Read the identified document and analyze: + +1. **Content Type Compliance** + - Is this strictly Tutorial / How-to / Explanation / Reference? + - Any mixed content that violates Diataxis? + +2. **Common Issues** + - Voice inconsistencies ("we", "let's" in technical descriptions) + - Character issues (em-dashes, curly quotes) + - Verbosity (can it be more concise?) + - Missing examples or unclear explanations + - Broken or missing cross-references + - Callout overuse (more than 3 Asides) + +3. **Structural Issues** + - Logical flow problems + - Missing sections (prerequisites, next steps) + - Heading hierarchy issues + - Code examples without context + +4. **Style Violations** + - "pgflow" capitalization + - Link format (trailing slashes) + - Frontmatter completeness + +Present analysis to user: +```markdown +## Analysis: [filename] + +**Content Type:** [Tutorial/How-to/Explanation/Reference] + +**Issues Found:** +- [Issue 1] +- [Issue 2] +... + +**Suggested Improvements:** +1. [Improvement 1] +2. [Improvement 2] +... +``` + +WAIT for user confirmation on which improvements to apply. + +### Step 3: Apply Improvements + +Based on user confirmation, apply the requested improvements following these guidelines: + +#### Voice and Perspective +```diff +# Fix impersonal language +- Let's set up pgflow ++ Set up pgflow + +- Our flow will process data ++ This flow processes data + +- We provide a CLI tool ++ pgflow provides a CLI tool +``` + +#### Simplification +- Remove redundant explanations +- Consolidate similar points +- Replace verbose phrases with concise alternatives +- Keep one example per concept (not three variations) + +#### Character Fixes +- Replace em-dashes (—) with hyphens (-) +- Replace curly quotes ("") with straight quotes ("") +- Replace curly apostrophes (') with straight apostrophes (') +- Replace ellipsis (…) with three periods (...) + +#### Code Example Improvements +- Add missing title attributes +- Add highlighting for important lines +- Add brief context before code blocks +- Ensure frame="none" for bash commands + +#### Cross-Reference Improvements +- Add "Learn More" sections with LinkCards +- Link to related concepts from how-tos +- Link to how-tos from explanations +- Add "Next Steps" to tutorials + +#### Callout Optimization +- Reduce to maximum 3 Asides per page +- Convert less important callouts to regular text +- Reserve Asides for: Prerequisites, Warnings, Key Tips + +### Step 4: Present Changes + +Show the user a summary of changes made: +```markdown +## Changes Applied to [filename] + +**Voice/Perspective:** [count] fixes +**Character fixes:** [count] fixes +**Simplified:** [description] +**Code examples:** [improvements] +**Cross-references:** [added links] +**Callouts:** [reduced from X to Y] + +[Show key excerpts of changes if helpful] +``` + +### Step 5: Write Updated File + +Apply all approved changes using the Edit tool. + +Confirm completion and suggest any follow-up actions (e.g., "might want to audit related docs for similar issues"). + +## Common Improvement Patterns + +### Pattern 1: Tutorial Voice Cleanup +**Before:** +> Now that we've installed pgflow, let's create our first flow. We'll define a simple workflow... + +**After:** +> Now that pgflow is installed, create your first flow. Define a simple workflow... + +### Pattern 2: Simplify Verbose Explanations +**Before:** +> In order to be able to successfully compile your flow definitions into SQL migrations that can then be applied to your database, you need to make sure that you have properly configured the pgflow compiler with the correct settings. + +**After:** +> Configure the compiler before compiling flows to SQL migrations. + +### Pattern 3: Add Missing Context +**Before:** +```typescript +export const myFlow = defineFlow({ + slug: "example", + execute: async (context) => { ... } +}); +``` + +**After:** +```typescript title="flows/my-flow.ts" +// Define a flow that processes user data +export const myFlow = defineFlow({ + slug: "example", + execute: async (context) => { ... } +}); +``` + +### Pattern 4: Reduce Callout Density +**Before:** 5 Asides breaking reading flow + +**After:** +- Keep: Prerequisites (caution) +- Keep: Critical warning (danger) +- Convert rest to: regular paragraphs or tables + +### Pattern 5: Add Cross-References +**Before:** Document ends abruptly + +**After:** +```markdown +## Learn More + + + + + +``` + +## Important Reminders + +- **Preserve user intent**: Don't change technical accuracy +- **Keep it simple**: Per MVP guidelines, avoid over-engineering improvements +- **Diataxis first**: Content type violations are highest priority +- **Style consistency**: Follow ALL character and voice guidelines +- **Test links**: Ensure all added links are valid +- **Maintain tone**: Keep approachable but professional + +## Special Cases + +**If document has mixed content (violates Diataxis):** +- Point this out to user +- Suggest using `/split-doc` command instead +- Only apply style fixes, not structural changes + +**If document is too long (>300 lines):** +- Suggest splitting into multiple pages +- Provide outline of how to split + +**If major structural issues:** +- Suggest complete rewrite using `/create-doc` +- Or create detailed restructuring plan for user approval + +## Output + +Use Edit tool to apply approved changes to the document. + +Confirm completion with summary of improvements made. diff --git a/.claude/commands/fix-doc-style.md b/.claude/commands/fix-doc-style.md new file mode 100644 index 000000000..bb4ab7e9d --- /dev/null +++ b/.claude/commands/fix-doc-style.md @@ -0,0 +1,204 @@ +You are tasked with quickly fixing style violations in documentation files. This is a fast, automated cleanup command. + +## Context + +Documentation root: `pkgs/website/src/content/docs/` + +Target file(s): + +$ARGUMENTS + + +## Process + +### Step 1: Identify Target File(s) + +**If specific path provided:** +- Use that file directly + +**If directory provided:** +- Find all .mdx files in that directory + +**If pattern provided (e.g., "all get-started docs"):** +- Use glob to find matching files +- Present list to user in a/b/c format or "all" +- WAIT for confirmation + +### Step 2: Run Automated Style Checks + +For each target file, check for these violations: + +#### 1. Character Issues (CRITICAL) +```typescript +// Check for and fix: +violations = { + emDash: /—/g, // Replace with: - + curlyQuoteLeft: /[""]/g, // Replace with: " + curlyQuoteRight: /[""]/g, // Replace with: " + curlyApostrophe: /'/g, // Replace with: ' + ellipsis: /…/g, // Replace with: ... + nbspSpace: /\u00A0/g, // Replace with regular space +} +``` + +#### 2. Naming Convention Violations +```typescript +// Check for and fix: +- PgFlow → pgflow +- pgFlow → pgflow +- PGFlow → pgflow +- Pgflow in prose → pgflow +// Exception: Keep "Pgflow" in class names (PascalCase) +``` + +#### 3. Link Format Issues +```typescript +// Check for and fix: +- Internal links without trailing slash: /path → /path/ +- Relative links: ../path → /absolute/path/ +``` + +#### 4. Common Voice Violations +```typescript +// Check for and flag (don't auto-fix, requires context): +- "we provide", "we use", "our system" +- "let's create", "let's start" +- "We'll be", "We're going to" +``` + +### Step 3: Apply Automatic Fixes + +Apply fixes for categories 1-3 automatically (character, naming, links). + +For category 4 (voice), only FLAG for user review - don't auto-fix. + +### Step 4: Present Results + +Show summary: +```markdown +## Style Fixes Applied: [filename(s)] + +**Character fixes:** [count] +- Em-dashes: [count] +- Curly quotes: [count] +- Ellipsis: [count] + +**Naming fixes:** [count] +- PgFlow/pgFlow → pgflow: [count] + +**Link fixes:** [count] +- Added trailing slashes: [count] + +**Voice issues flagged (manual review needed):** +[If any found, list them with line numbers] + +[If no issues] ✓ No style violations found! +``` + +### Step 5: Run Character Replacement Script + +After applying fixes with Edit tool, also run the official script to catch anything missed: +```bash +./scripts/replace-special-chars.sh [file] +``` + +Show script output. + +### Step 6: Verify Changes + +Quickly read the fixed file to confirm: +- No broken markdown syntax +- No broken code blocks +- Links still valid format +- Changes look correct + +If everything looks good, confirm completion. + +## Automated Fix Patterns + +### Pattern 1: Character Fixes +```markdown +# Before +Don't use curly quotes—they break things… it's problematic. + +# After +Don't use curly quotes-they break things... it's problematic. +``` + +### Pattern 2: Naming Fixes +```markdown +# Before +PgFlow is a PostgreSQL workflow engine. Install pgFlow using: + +# After +pgflow is a PostgreSQL workflow engine. Install pgflow using: +``` + +### Pattern 3: Link Fixes +```markdown +# Before +See [configuration](/reference/configuration) for details. + +# After +See [configuration](/reference/configuration/) for details. +``` + +### Pattern 4: Voice Issues (flagged only) +```markdown +# Flagged for manual review (line 42): +"Let's create our first flow" + +# Suggested change: +"Create your first flow" +``` + +## Batch Processing + +If multiple files selected, process each one and present aggregate summary: +```markdown +## Batch Style Fixes Complete + +**Files processed:** [count] + +**Total fixes:** +- Character issues: [count] +- Naming violations: [count] +- Link format: [count] + +**Files with voice issues needing review:** +- [filename1] ([count] issues) +- [filename2] ([count] issues) + +[Detailed breakdown per file if helpful] +``` + +## Important Reminders + +- **Character fixes are SAFE** - always apply automatically +- **Naming fixes are SAFE** - always apply (except in PascalCase class names) +- **Link fixes are SAFE** - trailing slashes don't break anything +- **Voice fixes need CONTEXT** - flag only, don't auto-change +- **Test after fixing** - make sure markdown still renders +- **Use official script** - run `replace-special-chars.sh` as final step + +## Special Cases + +**If file has significant voice issues:** +- Suggest using `/edit-doc` for comprehensive cleanup +- This command focuses on mechanical fixes + +**If file is very large (>500 lines):** +- Warn user about many fixes +- Ask confirmation before proceeding + +**If file has complex violations:** +- Fix what's mechanical +- Flag complex issues for manual review + +## Output + +Use Edit tool to apply all automatic fixes. + +Run `./scripts/replace-special-chars.sh` to catch any remaining issues. + +Present summary of all fixes applied and any issues flagged for review. diff --git a/.claude/commands/move-doc.md b/.claude/commands/move-doc.md new file mode 100644 index 000000000..2ee669cdc --- /dev/null +++ b/.claude/commands/move-doc.md @@ -0,0 +1,304 @@ +You are tasked with moving or renaming documentation files with proper git history preservation, link updates, and redirect configuration. + +## Context + +Documentation root: `pkgs/website/src/content/docs/` + +Current directory structure: + +!`tree pkgs/website/src/content/docs/ -L 2 -d` + + +Astro config location: `pkgs/website/astro.config.mjs` + +User request: + +$ARGUMENTS + + +## Multi-Step Process + +### Step 1: Parse Move Request + +Determine: +1. **Source file(s)**: Which file(s) to move +2. **Destination**: Where to move them +3. **Reason**: Why this move (helps with redirect reasoning) + +**If source unclear:** +- Search for matching files +- Present options to user +- WAIT for confirmation + +**If destination unclear:** +- Suggest destination based on content type and Diataxis +- Present suggestion to user +- WAIT for confirmation + +Present plan: +```markdown +## Move Plan + +**Source:** pkgs/website/src/content/docs/[old-path] +**Destination:** pkgs/website/src/content/docs/[new-path] +**Reason:** [brief explanation] + +**Old URL:** /[old-path]/ +**New URL:** /[new-path]/ +``` + +WAIT for user approval. + +### Step 2: Check for Inbound Links + +Before moving, find all files that link to this page: + +```bash +# Search for references to the old path +grep -r "[old-path]" pkgs/website/src/content/docs/ --include="*.mdx" +``` + +Present findings: +```markdown +## Impact Analysis + +**Files linking to this page:** [count] +[List files with line numbers if not too many] + +These links will need to be updated. +``` + +### Step 3: Create Destination Directory (if needed) + +If destination directory doesn't exist: +```bash +mkdir -p pkgs/website/src/content/docs/[destination-dir]/ +``` + +### Step 4: Move File with Git + +Use `git mv` to preserve history: +```bash +git mv pkgs/website/src/content/docs/[old-path] pkgs/website/src/content/docs/[new-path] +``` + +Confirm move successful. + +### Step 5: Update All Internal Links + +For each file that referenced the old path: +1. Read the file +2. Find all occurrences of old path +3. Replace with new path (maintaining trailing slashes) +4. Use Edit tool to update + +**Link patterns to update:** +- Markdown links: `[text](/old-path/)` → `[text](/new-path/)` +- LinkCard href: `href="/old-path/"` → `href="/new-path/"` +- Link attribute: `link="/old-path/"` → `link="/new-path/"` + +Present summary of link updates. + +### Step 6: Add Redirect Entry + +Read current redirects section from `pkgs/website/astro.config.mjs`. + +Add new redirect entry: +```javascript +redirects: { + // ... existing redirects ... + '/old-path/': '/new-path/', // [Brief reason for redirect] +} +``` + +Use Edit tool to add redirect to astro.config.mjs. + +### Step 7: Update Navigation (if needed) + +Check if moved file affects sidebar navigation in astro.config.mjs: + +**If using autogenerate:** +- No action needed (autogenerate will pick up new location) + +**If manually listed:** +- Update the link in sidebar configuration + +### Step 8: Verify and Test + +Run these checks: +1. **File exists at new location:** + ```bash + ls -la pkgs/website/src/content/docs/[new-path] + ``` + +2. **All links updated:** + ```bash + # Should return no results + grep -r "[old-path]" pkgs/website/src/content/docs/ --include="*.mdx" + ``` + +3. **Redirect added:** + ```bash + grep "[old-path]" pkgs/website/astro.config.mjs + ``` + +4. **Build passes:** + ```bash + pnpm nx build website + ``` + +Present verification results. + +### Step 9: Create Commit + +Prepare a structured commit message: +``` +refactor(docs): move [filename] to [new-location] + +- Move: [old-path] → [new-path] +- Update [count] internal links +- Add redirect for old URL +- Reason: [brief explanation] + +🤖 Generated with Claude Code +Co-Authored-By: Claude +``` + +Present commit message to user. + +If approved, create commit: +```bash +git add -A && git commit -m "$(cat <<'EOF' +[commit message here] +EOF +)" +``` + +## Common Move Patterns + +### Pattern 1: Reorganization (Build → Develop) +``` +FROM: pkgs/website/src/content/docs/how-to/create-tasks.mdx +TO: pkgs/website/src/content/docs/develop/authoring/create-tasks.mdx + +Redirect: '/how-to/create-tasks/': '/develop/authoring/create-tasks/' +``` + +### Pattern 2: Content Type Correction (Tutorial → Concept) +``` +FROM: pkgs/website/src/content/docs/get-started/understanding-flows.mdx +TO: pkgs/website/src/content/docs/concepts/flows/understanding-flows.mdx + +Redirect: '/get-started/understanding-flows/': '/concepts/flows/understanding-flows/' +Reason: Content is explanatory, not tutorial +``` + +### Pattern 3: Grouping Related Content +``` +FROM: pkgs/website/src/content/docs/reference/configuration.mdx +TO: pkgs/website/src/content/docs/reference/configuration/flow-config.mdx + +Redirect: '/reference/configuration/': '/reference/configuration/flow-config/' +Note: May need index.mdx in configuration/ directory +``` + +## Batch Moves + +If multiple files need moving together: + +### Step 1: Present Batch Plan +```markdown +## Batch Move Plan + +1. [file1] → [dest1] +2. [file2] → [dest2] +... + +**Total files:** [count] +**Redirects to add:** [count] +**Estimated link updates:** [count] +``` + +WAIT for approval. + +### Step 2: Process Each File +- Move all files with git mv +- Collect all link updates needed +- Update all links in one pass +- Add all redirects in one edit + +### Step 3: Verify Batch +- Check all files moved +- Check all links updated +- Check all redirects added +- Run build + +## Important Reminders + +- **Always use git mv** - preserves file history +- **Always add redirects** - never break old URLs +- **Update ALL links** - grep comprehensively +- **Test build** - catch broken links early +- **Commit atomically** - one logical move per commit (or one batch) +- **Clear commit messages** - explain the why + +## Error Handling + +**If destination file already exists:** +- Warn user +- Ask if should overwrite or choose different name +- Never silently overwrite + +**If links can't be auto-updated:** +- Flag them for manual review +- Show context around each link +- Ask user how to handle + +**If build fails after move:** +- Show build error +- Try to identify cause +- Offer to revert if needed + +**If too many links to update (>20):** +- Warn user about large impact +- Ask for confirmation before proceeding +- Consider if reorganization plan needs adjustment + +## Special Cases + +**Moving index.mdx files:** +- These affect parent directory URLs +- May need multiple redirects (with and without /index/) +- Check sidebar configuration carefully + +**Moving files with anchors:** +- Update links with anchors: `/old-path/#section` → `/new-path/#section` +- Grep for anchor references + +**Moving to existing directories:** +- Check for naming conflicts +- Verify autogenerate patterns still work + +**Cross-package moves:** +- Very rare, but if moving between packages +- Update package-specific config +- More complex redirect handling + +## Output + +Use these tools: +1. **Bash** - for git mv, directory creation, verification +2. **Edit** - for link updates and redirect additions +3. **Grep** - for finding references + +Present clear summary of all changes: +```markdown +## Move Complete: [filename] + +✓ File moved (git history preserved) +✓ [count] links updated across [count] files +✓ Redirect added to astro.config.mjs +✓ Build verification passed + +**Commit created** - ready to push +``` diff --git a/.claude/commands/simplify-doc.md b/.claude/commands/simplify-doc.md new file mode 100644 index 000000000..8a936bbfa --- /dev/null +++ b/.claude/commands/simplify-doc.md @@ -0,0 +1,413 @@ +You are tasked with simplifying documentation by reducing verbosity, improving clarity, and making content more scannable while preserving accuracy and completeness. + +## Context + +Documentation root: `pkgs/website/src/content/docs/` + +Target document: + +$ARGUMENTS + + +## Core Principle + +**MVP mindset:** Focus on 80% of value with 20% of effort. Cut ruthlessly. Users value clarity over comprehensiveness. + +## Process + +### Step 1: Identify Target and Baseline + +Read the target document. + +Measure baseline metrics: +- Total word count +- Number of sentences +- Number of code examples +- Number of sections +- Average sentence length + +Present baseline: +```markdown +## Document Analysis: [filename] + +**Current metrics:** +- Words: [count] +- Sentences: [count] +- Avg sentence length: [count] words +- Code examples: [count] +- Sections: [count] + +**Assessment:** [Verbose/Appropriate/Concise] +``` + +### Step 2: Identify Simplification Opportunities + +Analyze the document for these patterns: + +#### 1. REDUNDANCY +- [ ] Repetitive explanations +- [ ] Same point made multiple ways +- [ ] Redundant examples +- [ ] Duplicate information across sections + +#### 2. VERBOSITY +- [ ] Long-winded sentences (>25 words) +- [ ] Unnecessary qualifiers ("very", "really", "actually") +- [ ] Passive voice where active is clearer +- [ ] Complex phrases with simple alternatives + +#### 3. OVER-EXPLANATION +- [ ] Explaining obvious things +- [ ] Too much context before getting to point +- [ ] Multiple examples when one suffices +- [ ] Details that belong in reference, not here + +#### 4. POOR STRUCTURE +- [ ] Buried lede (main point not upfront) +- [ ] Rambling paragraphs +- [ ] Unclear section organization +- [ ] Missing scanning aids (lists, tables, callouts) + +#### 5. CODE BLOAT +- [ ] Code examples too long +- [ ] Showing full files when snippet would work +- [ ] Excessive comments in code +- [ ] Multiple similar examples + +Present findings: +```markdown +## Simplification Opportunities + +**Redundancy:** [count] instances +- [Example 1] +- [Example 2] + +**Verbosity:** [count] sentences to shorten +- [Example with word count] + +**Over-explanation:** [count] sections to trim +- [What can be cut or moved] + +**Structure:** [improvements needed] +- [Specific structural changes] + +**Code:** [count] examples to simplify +- [Which examples] + +**Target reduction:** [X]% fewer words +``` + +WAIT for user confirmation on which simplifications to apply. + +### Step 3: Apply Simplifications + +#### Technique 1: Sentence Reduction + +**Remove filler words:** +```markdown +# Before (28 words) +In order to be able to successfully start your flow, you need to first make sure that you have properly configured all of the necessary settings in your configuration file. + +# After (12 words) +Configure the required settings before starting your flow. +``` + +**Use active voice:** +```markdown +# Before (passive, 10 words) +The flow is defined using the defineFlow function. + +# After (active, 7 words) +Define flows using the defineFlow function. +``` + +**Remove qualifiers:** +```markdown +# Before +This is actually very important and you should really try to... + +# After +This is important. Try to... +``` + +#### Technique 2: Consolidate Repetition + +**Before (3 paragraphs saying same thing):** +> First paragraph explaining concept... +> Second paragraph re-explaining same concept... +> Third paragraph example of that same concept... + +**After (1 paragraph):** +> Single clear explanation with inline example. + +#### Technique 3: Trim Over-Explanation + +**Remove obvious context:** +```markdown +# Before +In the world of software development, when you're working with asynchronous operations, which are operations that don't complete immediately and might take some time to finish, you need to handle them properly... + +# After +Handle asynchronous operations with: +``` + +**Move detail to reference:** +```markdown +# Before (in how-to guide) +The maxAttempts option accepts a number between 1 and 100, with a default of 3. This controls how many times the task will retry. The baseDelay option controls the initial delay... + +# After +Configure retries: +- `maxAttempts`: number of retry attempts (default: 3) + +See [full configuration reference](/reference/configuration/) for all options. +``` + +#### Technique 4: Improve Structure for Scanning + +**Use lists instead of paragraphs:** +```markdown +# Before (paragraph) +The flow needs several things to work properly. First, it needs a slug which must be unique. Second, it needs task definitions. Third, it needs proper error handling configured. + +# After (list) +Each flow requires: +- Unique slug +- Task definitions +- Error handling configuration +``` + +**Use tables for comparisons:** +```markdown +# Before (paragraphs) +When you use single mode, the step runs once... +In array mode, the step runs multiple times... +With map mode, each iteration... + +# After (table) +| Mode | Behavior | Use When | +|------|----------|----------| +| single | Runs once | ... | +| array | Runs per item | ... | +| map | Parallel iteration | ... | +``` + +#### Technique 5: Simplify Code Examples + +**Show only relevant parts:** +```typescript +// Before (full file, 40 lines) +import { defineFlow } from "@pgflow/dsl"; +import { doThing1 } from "./tasks/thing1"; +import { doThing2 } from "./tasks/thing2"; +// ... many more imports + +export const myFlow = defineFlow({ + slug: "example", + execute: async (context) => { + // ... lots of code + } +}); + +// After (essential parts, 10 lines) +export const myFlow = defineFlow({ + slug: "example", + execute: async (context) => { + // Focus on the relevant part only + const result = await context.step("process", async () => { + return doProcessing(); + }); + } +}); +``` + +**Remove obvious comments:** +```typescript +// Before +// This defines a step +const result = await context.step( + "process", // The step slug + async () => { // The handler function + return data; // Return the data + } +); + +// After +const result = await context.step("process", async () => { + return data; +}); +``` + +### Step 4: Present Simplified Version + +Show before/after comparison: +```markdown +## Simplification Results + +**Before:** [X] words, [Y] sentences +**After:** [X] words, [Y] sentences +**Reduction:** [Z]% + +### Key Changes + +1. **Section A:** Reduced from [X] to [Y] words + - Removed: [What was cut] + - Kept: [What was preserved] + +2. **Section B:** Consolidated 3 examples into 1 + - Removed: [Which examples] + - Kept: [The clearest example] + +3. **Code Examples:** Simplified [count] examples + - Average reduction: [X]% + +[Show key excerpts demonstrating improvements] +``` + +WAIT for user approval before applying changes. + +### Step 5: Apply Changes and Verify + +Use Edit tool to apply all approved simplifications. + +After applying, verify: +- [ ] Accuracy preserved (no technical errors introduced) +- [ ] Completeness maintained (no essential info removed) +- [ ] Readability improved (easier to scan and understand) +- [ ] Code examples still work +- [ ] Links still valid + +Present final metrics: +```markdown +## Simplification Complete + +**Final metrics:** +- Words: [count] ([X]% reduction) +- Sentences: [count] ([Y]% reduction) +- Avg sentence length: [count] words (was [old]) +- Code examples: [count] (was [old]) + +**Readability improved:** [Yes/No] +**Accuracy preserved:** [Yes/No] +``` + +## Common Simplification Patterns + +### Pattern 1: Remove Preamble +```markdown +# Before +Before we dive into the details of how to configure your flows, it's important to understand that pgflow provides a flexible configuration system that allows you to... + +# After +Configure flows using these options: +``` + +### Pattern 2: Combine Short Sections +```markdown +# Before +## Section 1 +One paragraph. + +## Section 2 +One paragraph. + +## Section 3 +One paragraph. + +# After +## Combined Topic +- Point from section 1 +- Point from section 2 +- Point from section 3 +``` + +### Pattern 3: Extract to Reference +```markdown +# Before (in how-to guide) +Detailed explanation of every configuration option with types, defaults, constraints... + +# After +See [Configuration Reference](/reference/configuration/) for all options. + +This guide shows common patterns: +``` + +### Pattern 4: Replace Examples with Description +```markdown +# Before +Here's example 1 (10 lines)... +Here's example 2 (10 lines)... +Here's example 3 (10 lines)... + +# After +Common patterns: +- Pattern 1: [description] +- Pattern 2: [description] + +Example: +[One clear example, 10 lines] +``` + +## Simplification Guidelines + +### DO: +- Remove redundancy ruthlessly +- Use active voice +- Front-load conclusions +- Prefer lists over paragraphs +- Use tables for comparisons +- Show minimal working examples +- Link to detail instead of including +- Use "you" in instructions, not "we" + +### DON'T: +- Remove essential technical details +- Sacrifice accuracy for brevity +- Cut examples entirely (users need them) +- Remove all explanation (some context needed) +- Make sentences too terse (clarity matters) +- Remove prerequisites or warnings + +## Target Word Reductions + +**Good simplification:** +- Verbose docs (>300 lines): Target 30-40% reduction +- Medium docs (150-300 lines): Target 15-25% reduction +- Concise docs (<150 lines): Target 5-10% reduction + +**Red flags:** +- If reducing by >50%, may be removing too much +- If reducing by <10% on verbose doc, may be too timid + +## Important Reminders + +- **Clarity > Brevity** - Never sacrifice understanding for word count +- **Accuracy is sacred** - Double-check technical details +- **MVP mindset** - Focus on core value, cut nice-to-haves +- **User respect** - Users' time is valuable, don't waste it +- **Test examples** - Ensure simplified code still works +- **Preserve voice** - Keep approachable, professional tone + +## Special Cases + +**If document is already concise (<150 lines, <10 words/sentence):** +- Report "Document is already well-optimized" +- Suggest focusing on other issues (style, structure) + +**If document needs splitting, not simplifying:** +- Mixed content causing length +- Suggest `/audit-doc` to identify violations +- May need to move content, not cut it + +**If heavy technical reference:** +- Be conservative with simplification +- Completeness matters more than brevity +- Focus on structure improvements instead + +## Output + +Use Edit tool to apply approved simplifications. + +Present clear before/after metrics showing improvement. + +Confirm that accuracy and essential content are preserved. diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 000000000..b96df51af --- /dev/null +++ b/PLAN.md @@ -0,0 +1,362 @@ +# Documentation Reorganization Execution Plan + +Based on `guide.md` - reorganize documentation with physical folder structure matching sidebar organization. + +## Phase 1: Directory Renames & File Moves (using git mv) + +### Step 1.1: Create new directory structure + +```bash +# Create all subdirectories +mkdir -p pkgs/website/src/content/docs/develop/{authoring,config-tuning,manage} +mkdir -p pkgs/website/src/content/docs/operate/{deploy,observe,maintain} +mkdir -p pkgs/website/src/content/docs/concepts/{overview,dsl} +mkdir -p pkgs/website/src/content/docs/reference/{configuration,apis,queue-worker} +``` + +### Step 1.2: Move files with git mv + +#### Develop section (from build/) + +```bash +git mv pkgs/website/src/content/docs/build/organize-flow-code.mdx pkgs/website/src/content/docs/develop/authoring/organize-flow-code.mdx +git mv pkgs/website/src/content/docs/build/create-reusable-tasks.mdx pkgs/website/src/content/docs/develop/authoring/create-reusable-tasks.mdx +git mv pkgs/website/src/content/docs/build/batch-process-with-map.mdx pkgs/website/src/content/docs/develop/authoring/batch-process-with-map.mdx +git mv pkgs/website/src/content/docs/build/update-flow-options.mdx pkgs/website/src/content/docs/develop/config-tuning/update-flow-options.mdx +git mv pkgs/website/src/content/docs/build/version-flows.mdx pkgs/website/src/content/docs/develop/manage/version-flows.mdx +git mv pkgs/website/src/content/docs/build/delete-flows.mdx pkgs/website/src/content/docs/develop/manage/delete-flows.mdx +``` + +#### Operate section + +```bash +# Deploy +git mv pkgs/website/src/content/docs/production/supabase/deploy.mdx pkgs/website/src/content/docs/operate/deploy/deploy-to-supabase.mdx +git mv pkgs/website/src/content/docs/production/supabase/keep-workers-running.mdx pkgs/website/src/content/docs/operate/deploy/keep-workers-running.mdx + +# Observe +git mv pkgs/website/src/content/docs/build/monitor-execution.mdx pkgs/website/src/content/docs/operate/observe/monitor-execution.mdx +git mv pkgs/website/src/content/docs/edge-worker/getting-started/observability.mdx pkgs/website/src/content/docs/operate/observe/monitor-workers-health.mdx + +# Maintain +git mv pkgs/website/src/content/docs/production/update-pgflow.mdx pkgs/website/src/content/docs/operate/maintain/update-pgflow.mdx +git mv pkgs/website/src/content/docs/production/prune-records.mdx pkgs/website/src/content/docs/operate/maintain/prune-records.mdx +git mv pkgs/website/src/content/docs/production/connection-string.mdx pkgs/website/src/content/docs/operate/maintain/connection-string.mdx +``` + +#### Concepts section + +```bash +# Overview +git mv pkgs/website/src/content/docs/concepts/index.mdx pkgs/website/src/content/docs/concepts/overview/index.mdx +git mv pkgs/website/src/content/docs/concepts/how-pgflow-works.mdx pkgs/website/src/content/docs/concepts/overview/how-pgflow-works.mdx + +# DSL +git mv pkgs/website/src/content/docs/concepts/flow-dsl.mdx pkgs/website/src/content/docs/concepts/dsl/flow-dsl.mdx +git mv pkgs/website/src/content/docs/concepts/map-steps.mdx pkgs/website/src/content/docs/concepts/dsl/map-steps.mdx +git mv pkgs/website/src/content/docs/concepts/context.mdx pkgs/website/src/content/docs/concepts/dsl/context.mdx +git mv pkgs/website/src/content/docs/build/naming-steps.mdx pkgs/website/src/content/docs/concepts/dsl/naming-steps.mdx +``` + +#### Reference section + +```bash +# Configuration +git mv pkgs/website/src/content/docs/get-started/configuration.mdx pkgs/website/src/content/docs/reference/configuration/configuration.mdx + +# APIs +git mv pkgs/website/src/content/docs/build/compile-manually.mdx pkgs/website/src/content/docs/reference/apis/compile-api.mdx +git mv pkgs/website/src/content/docs/advanced/manual-installation.mdx pkgs/website/src/content/docs/reference/apis/manual-installation.mdx + +# Queue Worker +git mv pkgs/website/src/content/docs/edge-worker/getting-started/configuration.mdx pkgs/website/src/content/docs/reference/queue-worker/configuration.mdx +git mv pkgs/website/src/content/docs/edge-worker/how-it-works.mdx pkgs/website/src/content/docs/reference/queue-worker/how-it-works.mdx +``` + +#### Comparisons + +```bash +# Rename vs/ to comparisons/ +git mv pkgs/website/src/content/docs/vs pkgs/website/src/content/docs/comparisons +``` + +### Step 1.3: Clean up empty directories + +After moving files, these should be empty: +- `build/` - delete +- `production/supabase/` and `production/` - delete +- `advanced/` - delete +- `edge-worker/getting-started/` and `edge-worker/` (keep `_drafts` if needed) - delete + +--- + +## Phase 2: Update Page Frontmatter + +### reference/apis/compile-api.mdx +Change title from "Manually Compile Flow to SQL" to: +```yaml +title: Compile API +``` + +### operate/observe/monitor-workers-health.mdx +Change title to: +```yaml +title: Monitor workers health +``` + +--- + +## Phase 3: Content Updates + +### 3.1 get-started/index.mdx +Add two cards at top of page (after frontmatter, before existing content): +- **Card 1**: "Create your first flow" → `/get-started/flows/create-flow/` +- **Card 2**: "…or run simple jobs" → `/get-started/background-jobs/create-worker/` (marked as optional/smaller) + +### 3.2 get-started/flows/run-flow.mdx +Add "Where next?" section at end with three cards: +1. **Ship to Supabase** → `/operate/deploy/deploy-to-supabase/` +2. **Make flows resilient (retries & timeouts)** → `/reference/configuration/configuration/#flow-options` +3. **Observe runs with SQL** → `/operate/observe/monitor-execution/` + +### 3.3 reference/configuration/configuration.mdx +Add anchor IDs to sections: +- `#flow-options` - for Flow/Step configuration section +- `#edge-worker-options` - for EdgeWorker configuration section +- `#queue-deltas` - add small note section listing 2-3 differences between flow mode and queue mode + +### 3.4 Homepage (index.mdx) +Update CTAs: +- **Primary**: "Create Your First Workflow" (already correct, keep pointing to `/get-started/installation/`) +- **Secondary**: Update to point to background jobs option (add anchor `#background-jobs` reference or adjust target) + +--- + +## Phase 4: Update Sidebar Configuration (astro.config.mjs) + +### 4.1 Rename topic labels +- "Build" → "Develop" +- "Production" → "Operate" +- "Configuration" → "Reference" (in plugin config) +- "vs" → "Comparisons" + +### 4.2 Restructure sidebar with subgroups + +**Get Started/** (no changes to structure, already correct) + +**Develop/** (with subgroups) +```javascript +{ + label: 'Develop', + icon: 'puzzle', + items: [ + { + label: 'Authoring', + items: [ + { autogenerate: { directory: 'develop/authoring/' } } + ] + }, + { + label: 'Config & Tuning', + items: [ + { autogenerate: { directory: 'develop/config-tuning/' } } + ] + }, + { + label: 'Manage', + items: [ + { autogenerate: { directory: 'develop/manage/' } } + ] + } + ] +} +``` + +**Operate/** (with subgroups) +```javascript +{ + label: 'Operate', + icon: 'setting', + items: [ + { + label: 'Deploy', + items: [ + { autogenerate: { directory: 'operate/deploy/' } } + ] + }, + { + label: 'Observe', + items: [ + { autogenerate: { directory: 'operate/observe/' } } + ] + }, + { + label: 'Maintain', + items: [ + { autogenerate: { directory: 'operate/maintain/' } } + ] + } + ] +} +``` + +**Concepts/** (with subgroups) +```javascript +{ + label: 'Concepts', + icon: 'information', + items: [ + { + label: 'Overview', + items: [ + { autogenerate: { directory: 'concepts/overview/' } } + ] + }, + { + label: 'DSL', + items: [ + { autogenerate: { directory: 'concepts/dsl/' } } + ] + } + ] +} +``` + +**Reference/** (with subgroups) +```javascript +{ + label: 'Reference', + icon: 'document', + items: [ + { + label: 'Configuration', + items: [ + { autogenerate: { directory: 'reference/configuration/' } } + ] + }, + { + label: 'APIs', + items: [ + { autogenerate: { directory: 'reference/apis/' } } + ] + }, + { + label: 'Queue Worker', + items: [ + { autogenerate: { directory: 'reference/queue-worker/' } } + ] + } + ] +} +``` + +**Tutorials/** (no changes) + +**Comparisons/** (rename from vs) +```javascript +{ + label: 'Comparisons', + icon: 'puzzle', + items: [ + { autogenerate: { directory: 'comparisons/' } } + ] +} +``` + +--- + +## Phase 5: Add Redirects (astro.config.mjs) + +Add redirects for all moved files (~30 redirects): + +```javascript +redirects: { + // Existing redirects... + + // Develop (from build/) + '/build/organize-flow-code/': '/develop/authoring/organize-flow-code/', + '/build/create-reusable-tasks/': '/develop/authoring/create-reusable-tasks/', + '/build/batch-process-with-map/': '/develop/authoring/batch-process-with-map/', + '/build/update-flow-options/': '/develop/config-tuning/update-flow-options/', + '/build/version-flows/': '/develop/manage/version-flows/', + '/build/delete-flows/': '/develop/manage/delete-flows/', + '/build/naming-steps/': '/concepts/dsl/naming-steps/', + '/build/monitor-execution/': '/operate/observe/monitor-execution/', + '/build/compile-manually/': '/reference/apis/compile-api/', + + // Operate (from production/) + '/production/supabase/deploy/': '/operate/deploy/deploy-to-supabase/', + '/production/supabase/keep-workers-running/': '/operate/deploy/keep-workers-running/', + '/production/update-pgflow/': '/operate/maintain/update-pgflow/', + '/production/prune-records/': '/operate/maintain/prune-records/', + '/production/connection-string/': '/operate/maintain/connection-string/', + + // Reference + '/get-started/configuration/': '/reference/configuration/configuration/', + '/advanced/manual-installation/': '/reference/apis/manual-installation/', + + // Edge Worker to Reference + '/edge-worker/getting-started/configuration/': '/reference/queue-worker/configuration/', + '/edge-worker/getting-started/observability/': '/operate/observe/monitor-workers-health/', + '/edge-worker/how-it-works/': '/reference/queue-worker/how-it-works/', + + // Concepts + '/concepts/': '/concepts/overview/', + '/concepts/flow-dsl/': '/concepts/dsl/flow-dsl/', + '/concepts/map-steps/': '/concepts/dsl/map-steps/', + '/concepts/context/': '/concepts/dsl/context/', + + // Comparisons + '/vs/': '/comparisons/', + '/vs/dbos/': '/comparisons/dbos/', + '/vs/inngest/': '/comparisons/inngest/', + '/vs/trigger/': '/comparisons/trigger/', +} +``` + +--- + +## Phase 6: Fix Links & Build + +### 6.1 Run build +```bash +pnpm nx build website +``` + +### 6.2 Identify broken links +Look for link validation errors in build output + +### 6.3 Fix links systematically +Use sed or manual edits to update internal links to new paths + +### 6.4 Verify build passes +```bash +pnpm nx build website +``` + +--- + +## Expected Outcomes + +After completion: +- ✅ URL structure matches sidebar organization +- ✅ All old URLs redirect to new locations +- ✅ "Develop" and "Operate" replace "Build" and "Production" +- ✅ Reference section contains configuration and API docs +- ✅ Queue worker docs are in Reference section +- ✅ Concepts organized into Overview and DSL subgroups +- ✅ Get Started shows clear choice between flows and background jobs +- ✅ All links work and build passes + +--- + +## Execution Order + +1. **Phase 1**: File moves (safest, preserves git history) +2. **Phase 2**: Frontmatter updates (simple, low risk) +3. **Phase 3**: Content updates (adds navigation aids) +4. **Phase 4**: Sidebar configuration (changes navigation structure) +5. **Phase 5**: Redirects (ensures old URLs work) +6. **Phase 6**: Fix any resulting link issues + +Each phase can be committed separately for easy rollback if needed. diff --git a/PLAN2.md b/PLAN2.md new file mode 100644 index 000000000..a770d046e --- /dev/null +++ b/PLAN2.md @@ -0,0 +1,215 @@ +# Navigation Fix - Implementation Plan + +Based on tech writer feedback (answers.md) adapted to our current structure. + +## Core Approach: Option 2.5 + +**Default to Flows** with persistent secondary path to Background Jobs. No forced overview, minimal upfront decisions. + +## Changes to Implement + +### 1. Landing Page CTAs (Keep Current) + +✅ **No change needed** - current CTAs are correct: +```yaml +Primary: "Get Started" → /get-started/installation/ +Secondary: "How It Works" → /concepts/overview/how-pgflow-works/ +``` + +**Rationale:** Installation is required for both paths, so it's the right first step. + +### 2. Sidebar Structure (Keep Current with Minor Tweak) + +✅ **Keep current nested structure** - it's correct: +``` +Get Started (link: /get-started/installation/) + - Installation + - FAQ + - Flows/ + - Create Flow + - Compile Flow + - Run Flow + - Background Jobs/ + - Create Worker +``` + +**Why this works:** +- "Flows/" contains the sequential tutorial (create → compile → run) +- "Background Jobs/" is separate alternative path +- Nested structure shows they're both multi-step processes +- Visual hierarchy through ordering (Flows first) + +**Rationale:** Tech writer suggested flat structure doesn't account for our multi-step tutorials. Our nested structure is better. + +### 3. Remove Get Started Overview Page + +❌ **Delete `/get-started/index.mdx`** + +**Current content:** +- "Choose your path" cards (flows vs bg jobs) +- Links to installation +- Redundant with new decision strip + +**Why remove:** +- Adds friction before installation +- Decision should come AFTER installation +- Forces reading when users want to act +- Installation is the actual first step + +**Sidebar impact:** +- Get Started topic links directly to Installation +- Remove "Overview" from sidebar items +- Installation becomes the landing page + +### 4. Add Decision Strip to Installation Page + +✅ **Add at end of `/get-started/installation.mdx`:** + +```markdown +## Next Steps + + + + **Recommended:** Build multi-step workflows with dependencies, retries, and full observability. + + Perfect for: AI pipelines, data processing, complex orchestration + + [Start building →](/get-started/flows/create-flow/) + + + + **Simpler alternative:** Just need background task processing with retries? + + Perfect for: Async tasks, webhooks, one-off jobs + + [Create a worker →](/get-started/background-jobs/create-worker/) + + + + +``` + +**Visual hierarchy:** +- Flows card: Larger, "Recommended" badge, primary styling +- BG Jobs card: Smaller, "Or:" prefix, secondary styling +- Clear nudge toward flows without hiding jobs + +### 5. Optional: Compare Page (Future) + +⚠️ **Not implementing now** - would be useful later: + +Potential page: `/get-started/flows-vs-background-jobs/` or `/concepts/flows-vs-background-jobs/` + +**Content (future):** +- Side-by-side comparison table +- When to use each +- Technical differences +- Link from FAQ or concepts + +**Why not now:** +- Can be added later if users request it +- Not blocking for launch +- Decision strip is sufficient + +--- + +## Implementation Steps + +### Step 1: Remove Get Started Overview +```bash +git rm pkgs/website/src/content/docs/get-started/index.mdx +``` + +### Step 2: Update Sidebar Config +Remove "Overview" item from Get Started sidebar: +```javascript +{ + label: 'Get Started', + icon: 'rocket', + link: '/get-started/installation/', + id: 'get-started', + items: [ + // Remove: { label: 'Overview', link: '/get-started/' }, + { label: 'Installation', link: '/get-started/installation/' }, + { label: 'FAQ', link: '/get-started/faq/' }, + { + label: 'Flows', + autogenerate: { directory: 'get-started/flows/' }, + }, + { + label: 'Background Jobs', + autogenerate: { directory: 'get-started/background-jobs/' }, + }, + ], +} +``` + +### Step 3: Add Decision Strip to Installation +At end of `/get-started/installation.mdx`, add the "Next Steps" section with two cards (see above). + +### Step 4: Add Redirect +Since we're removing `/get-started/` index, add redirect: +```javascript +redirects: { + '/get-started/': '/get-started/installation/', +} +``` + +--- + +## User Journey After Changes + +### Flow User (90% case): +``` +1. Land on homepage → "Get Started" +2. Install pgflow +3. See decision strip → Choose "Create Your First Flow" (emphasized) +4. Follow tutorial: create → compile → run +``` + +### BG Jobs User (10% case): +``` +1. Land on homepage → "Get Started" +2. Install pgflow +3. See decision strip → Choose "Run Background Jobs" (visible alternative) +4. Create worker, done +``` + +**Key improvement:** Both paths go through installation first, then make informed choice with clear nudge toward flows. + +--- + +## Rationale + +**Why this works:** +1. ✅ Minimal upfront decisions (just "Get Started") +2. ✅ Installation is required step (shown first) +3. ✅ Choice comes AFTER installation (when relevant) +4. ✅ Clear visual hierarchy (Flows emphasized) +5. ✅ BG Jobs still discoverable (not hidden) +6. ✅ Respects scanning behavior (big buttons, not text) +7. ✅ Progressive disclosure (complexity after install) + +**Aligns with tech writer advice:** +- Default to flows ✅ +- Persistent secondary path ✅ +- Post-install choice strip ✅ +- No forced overview ✅ +- Visual hierarchy ✅ + +--- + +## Pre-Launch Checklist + +Before Show HN: +- [ ] Remove overview page +- [ ] Update sidebar config +- [ ] Add decision strip to installation +- [ ] Add redirect +- [ ] Test build passes +- [ ] Verify all links work +- [ ] Check mobile display of decision cards + +**Ship this for Show HN! 🚀** diff --git a/pkgs/website/astro.config.mjs b/pkgs/website/astro.config.mjs index a3e154479..a7c256baa 100644 --- a/pkgs/website/astro.config.mjs +++ b/pkgs/website/astro.config.mjs @@ -56,30 +56,97 @@ export default defineConfig({ // Page rename redirects '/concepts/array-and-map-steps/': '/concepts/map-steps/', - // Existing redirects + // Get Started reorganization + '/get-started/': '/get-started/installation/', + '/getting-started/': '/get-started/', + '/getting-started/install-pgflow/': '/get-started/installation/', + '/getting-started/create-first-flow/': '/get-started/flows/create-flow/', + '/getting-started/compile-to-sql/': '/get-started/flows/compile-flow/', + '/getting-started/run-flow/': '/get-started/flows/run-flow/', + '/getting-started/update-pgflow/': '/deploy/maintain/update-pgflow/', + '/getting-started/configuration/': '/reference/configuration/configuration/', + + // Edge Worker reorganization + '/edge-worker/getting-started/create-first-worker/': + '/get-started/background-jobs/create-worker/', + '/edge-worker/getting-started/install-edge-worker/': + '/get-started/installation/', '/edge-worker/how-to/run-on-hosted-supabase/': - '/how-to/deploy-to-supabasecom/', - '/edge-worker/faq/': '/faq/', - '/edge-worker/how-to/': '/faq/', + '/deploy/supabase/deploy-first-flow/', + '/edge-worker/faq/': '/get-started/faq/', + '/edge-worker/how-to/': '/get-started/faq/', '/edge-worker/how-to/deploy-to-supabasecom/': - '/how-to/deploy-to-supabasecom/', - '/edge-worker/how-to/prepare-db-string/': '/how-to/prepare-db-string/', + '/deploy/supabase/deploy-first-flow/', + '/edge-worker/how-to/prepare-db-string/': '/deploy/maintain/connection-string/', + + // FAQ move + '/faq/': '/get-started/faq/', - // File rename redirects - '/how-to/version-your-flows/': '/how-to/version-flows/', + // How-to → Develop/Operate reorganization + '/how-to/': '/build/', + '/how-to/batch-process-with-map/': '/build/authoring/process-arrays-in-parallel/', + '/how-to/create-reusable-tasks/': '/build/authoring/create-reusable-tasks/', + '/how-to/monitor-flow-execution/': '/deploy/observe/monitor-execution/', + '/how-to/naming-steps/': '/concepts/flows/naming-steps/', + '/how-to/organize-flows-code/': '/build/authoring/organize-flow-code/', + '/how-to/version-flows/': '/build/version-flows/', + '/how-to/version-your-flows/': '/build/version-flows/', + '/develop/manage/version-flows/': '/build/version-flows/', + '/how-to/update-flow-options/': '/deploy/maintain/tune-flow-config/', + '/develop/config-tuning/update-flow-options/': '/deploy/maintain/tune-flow-config/', + '/develop/manage/update-flow-options/': '/deploy/maintain/tune-flow-config/', + '/how-to/delete-flow-and-data/': '/build/delete-flows/', + '/develop/manage/delete-flows/': '/build/delete-flows/', + '/how-to/manually-compile-flow/': '/reference/apis/compile-api/', + '/how-to/deploy-to-supabasecom/': '/deploy/supabase/deploy-first-flow/', + '/how-to/keep-workers-up/': '/deploy/supabase/keep-workers-running/', + '/operate/deploy/deploy-to-supabase/': '/deploy/supabase/update-deployed-flows/', + '/how-to/prepare-db-string/': '/deploy/maintain/connection-string/', + '/how-to/prune-old-records/': '/deploy/maintain/prune-records/', + '/how-to/manual-installation/': '/reference/apis/manual-installation/', - // New redirects for reorganization - '/explanations/': '/concepts/', - '/explanations/flow-dsl/': '/concepts/flow-dsl/', + // Develop → Build, Operate → Deploy rename + '/develop/': '/build/', + '/develop/authoring/create-reusable-tasks/': '/build/authoring/create-reusable-tasks/', + '/develop/authoring/organize-flow-code/': '/build/authoring/organize-flow-code/', + '/develop/authoring/process-arrays-in-parallel/': '/build/authoring/process-arrays-in-parallel/', + '/develop/version-flows/': '/build/version-flows/', + '/develop/delete-flows/': '/build/delete-flows/', + '/operate/': '/deploy/', + '/operate/deploy/deploy-first-flow/': '/deploy/supabase/deploy-first-flow/', + '/operate/deploy/keep-workers-running/': '/deploy/supabase/keep-workers-running/', + '/operate/deploy/update-deployed-flows/': '/deploy/supabase/update-deployed-flows/', + '/operate/observe/monitor-execution/': '/deploy/observe/monitor-execution/', + '/operate/observe/monitor-workers-health/': '/deploy/observe/monitor-workers-health/', + '/operate/maintain/connection-string/': '/deploy/maintain/connection-string/', + '/operate/maintain/prune-records/': '/deploy/maintain/prune-records/', + '/operate/maintain/tune-flow-config/': '/deploy/maintain/tune-flow-config/', + '/operate/maintain/update-pgflow/': '/deploy/maintain/update-pgflow/', + + // Explanations to Concepts/Comparisons + '/explanations/': '/concepts/overview/', + '/explanations/flow-dsl/': '/concepts/flows/understanding-flows/', '/explanations/comparison-to-dbos/': '/comparisons/dbos/', '/explanations/comparison-to-inngest/': '/comparisons/inngest/', '/explanations/comparison-to-trigger-dev/': '/comparisons/trigger/', - // Redirects for comparisons to vs rename - '/comparisons/': '/vs/', - '/comparisons/dbos/': '/vs/dbos/', - '/comparisons/inngest/': '/vs/inngest/', - '/comparisons/trigger/': '/vs/trigger/', + // Comparisons rename (vs → comparisons) + '/vs/': '/comparisons/', + '/vs/dbos/': '/comparisons/dbos/', + '/vs/inngest/': '/comparisons/inngest/', + '/vs/trigger/': '/comparisons/trigger/', + + // Edge Worker → Reference/Queue Worker + '/edge-worker/getting-started/configuration/': '/reference/queue-worker/configuration/', + '/edge-worker/how-it-works/': '/reference/queue-worker/how-it-works/', + '/edge-worker/getting-started/observability/': '/deploy/observe/monitor-workers-health/', + + // Concepts reorganization + '/concepts/': '/concepts/overview/', + '/concepts/flow-dsl/': '/concepts/flows/understanding-flows/', + '/concepts/map-steps/': '/concepts/flows/map-steps/', + '/concepts/context/': '/concepts/flows/context/', + '/concepts/how-pgflow-works/': '/concepts/architecture/how-pgflow-works/', }, integrations: [ @@ -184,130 +251,172 @@ export default defineConfig({ 'index', '**/index', 'tutorials/ai-web-scraper/*', - 'how-to/naming-steps', - 'how-to/update-flow-options', - 'faq', + 'concepts/flows/naming-steps', + 'deploy/maintain/tune-flow-config', + 'get-started/faq', 'news/**', 'hire/**', ], promote: [ - 'getting-started/install-pgflow', - 'getting-started/create-first-flow', - 'getting-started/compile-to-sql', - 'getting-started/run-flow', - 'concepts/how-pgflow-works', - 'concepts/flow-dsl', - 'how-to/create-reusable-tasks', - 'how-to/monitor-flow-execution', - 'how-to/version-flows', - 'how-to/organize-flows-code', + 'get-started/installation', + 'get-started/flows/create-flow', + 'get-started/flows/compile-flow', + 'get-started/flows/run-flow', + 'concepts/architecture/how-pgflow-works', + 'concepts/flows/understanding-flows', + 'build/authoring/create-reusable-tasks', + 'deploy/observe/monitor-execution', + 'build/version-flows', + 'build/authoring/organize-flow-code', ], demote: [ 'edge-worker/*', - 'vs/*', - 'how-to/deploy-to-supabasecom', - 'how-to/manual-installation', - 'how-to/prepare-db-string', - 'how-to/prune-old-records', - 'how-to/delete-flow-and-data', + 'reference/queue-worker/*', + 'comparisons/*', + 'deploy/supabase/deploy-first-flow', + 'deploy/supabase/update-deployed-flows', + 'reference/apis/manual-installation', + 'deploy/maintain/connection-string', + 'deploy/maintain/prune-records', + 'build/delete-flows', + 'project-status', ], }), starlightLinksValidator({ exclude: ['http://localhost*'] }), starlightSidebarTopics( [ { - label: 'News', - icon: 'pen', - link: '/news/', - id: 'news', + label: 'Get Started', + icon: 'rocket', + link: '/get-started/installation/', + id: 'get-started', items: [ + { label: 'Installation', link: '/get-started/installation/' }, + { + label: 'Flows', + autogenerate: { directory: 'get-started/flows/' }, + }, { - label: 'All Posts', - link: '/news/', + label: 'Background Jobs', + autogenerate: { directory: 'get-started/background-jobs/' }, }, + { label: 'FAQ', link: '/get-started/faq/' }, + { label: 'Project Status', link: '/project-status/' }, ], }, { - label: 'pgflow', - icon: 'open-book', - link: '/getting-started/install-pgflow/', - id: 'pgflow', + label: 'Build', + icon: 'pencil', + link: '/build/', + id: 'build', items: [ + { label: 'Overview', link: '/build/' }, { - label: 'START HERE', - autogenerate: { directory: 'getting-started/' }, + label: 'Authoring', + autogenerate: { directory: 'build/authoring/' }, }, + { label: 'Version flows', link: '/build/version-flows/' }, + { label: 'Delete flows', link: '/build/delete-flows/' }, + ], + }, + { + label: 'Deploy', + icon: 'cloud-download', + link: '/deploy/', + id: 'deploy', + items: [ + { label: 'Overview', link: '/deploy/' }, { - label: 'TUTORIALS', - collapsed: true, - items: [ - { - label: 'AI Web Scraper', - autogenerate: { - directory: 'tutorials/ai-web-scraper/', - collapsed: true, - }, - }, - ], + label: 'Supabase', + autogenerate: { directory: 'deploy/supabase/' }, }, { - label: 'HOW TO', - collapsed: true, - autogenerate: { directory: 'how-to/' }, + label: 'Observe', + autogenerate: { directory: 'deploy/observe/' }, }, { - label: 'CONCEPTS', - collapsed: true, - autogenerate: { directory: 'concepts/' }, + label: 'Maintain', + autogenerate: { directory: 'deploy/maintain/' }, }, + ], + }, + { + label: 'Concepts', + icon: 'puzzle', + link: '/concepts/', + id: 'concepts', + items: [ + { label: 'Overview', link: '/concepts/overview/' }, { - label: 'COMPARISONS', - collapsed: true, - autogenerate: { directory: 'vs/' }, + label: 'Architecture', + autogenerate: { directory: 'concepts/architecture/' }, }, { - label: 'FAQ - Common Questions', - link: '/faq/', + label: 'Defining Flows', + autogenerate: { directory: 'concepts/flows/' }, }, ], }, { - label: 'Edge Worker', - icon: 'open-book', - link: '/edge-worker/how-it-works/', - id: 'edge-worker', + label: 'Reference', + icon: 'document', + link: '/reference/', + id: 'reference', items: [ - { label: 'How it works?', link: '/edge-worker/how-it-works/' }, + { label: 'Overview', link: '/reference/' }, + { + label: 'Configuration', + autogenerate: { directory: 'reference/configuration/' }, + }, { - label: 'Getting started', - autogenerate: { directory: 'edge-worker/getting-started/' }, + label: 'APIs', + autogenerate: { directory: 'reference/apis/' }, }, { - label: 'How To', - items: [ - { - label: 'Deploy to Supabase.com', - link: '/how-to/deploy-to-supabasecom/', - }, - { - label: 'Prepare DB Connection String', - link: '/how-to/prepare-db-string/', - }, - ], + label: 'Queue Worker', + autogenerate: { directory: 'reference/queue-worker/' }, + }, + ], + }, + { + label: 'Tutorials', + icon: 'open-book', + link: '/tutorials/', + id: 'tutorials', + items: [ + { + label: 'AI Web Scraper', + autogenerate: { + directory: 'tutorials/ai-web-scraper/', + }, }, ], }, { - label: 'Found a bug?', - icon: 'github', - link: 'https://github.com/pgflow-dev/pgflow/issues/new', + label: 'Comparisons', + icon: 'random', + link: '/comparisons/', + id: 'comparisons', + items: [ + { label: 'Overview', link: '/comparisons/' }, + { label: 'DBOS', link: '/comparisons/dbos/' }, + { label: 'Inngest', link: '/comparisons/inngest/' }, + { label: 'Trigger.dev', link: '/comparisons/trigger/' }, + ], }, ], { - exclude: ['/author', '/demos', '/demo-colors'], - topics: { - news: ['/news', '/news/**/*'], - }, + exclude: [ + '/author', + '/demos', + '/demo-colors', + '/news', + '/news/**', + '/edge-worker', + '/edge-worker/**', + '/project-status', + ], + topics: {}, } ), ], diff --git a/pkgs/website/src/components/NotProductionReady.astro b/pkgs/website/src/components/NotProductionReady.astro index d6c3f49a2..a73594a27 100644 --- a/pkgs/website/src/components/NotProductionReady.astro +++ b/pkgs/website/src/components/NotProductionReady.astro @@ -2,6 +2,6 @@ import { Aside } from "@astrojs/starlight/components"; --- -