macalbert/envilder/doc-sync

Doc Sync: Cross-Surface Documentation Alignment

Audit and synchronize documentation across all surfaces to prevent drift.

When to Use

• After adding or changing a feature, CLI flag, or SDK capability
• After updating website content (DocsContent.astro, i18n strings)
• Before a release to verify all docs reflect current behavior
• When a code review flags outdated documentation

Documentation Surfaces

Procedure

1. Identify Scope

Determine which feature area to audit:

• CLI: root README, docs/pull-command.md, docs/push-command.md, website DocsContent
• GHA: github-action/README.md, docs/github-action.md, website DocsContent
• SDK (per runtime): src/sdks/{runtime}/README.md, examples/sdk/{runtime}/,

website DocsContent + Sdks.astro, i18n strings

• Full: all surfaces

2. Extract Source of Truth

For each feature area, identify the authoritative source:

3. Audit Each Surface

For each documentation surface, check:

• [ ] Code examples compile/run: verify syntax matches current API
• [ ] CLI flags match: documented flags exist in Cli.ts
• [ ] GHA inputs match: documented inputs exist in action.yml
• [ ] SDK methods match: documented methods exist in source
• [ ] Install commands correct: package names, versions, registries
• [ ] Provider names consistent: aws/azure naming across all docs
• [ ] Links not broken: internal cross-references resolve
• [ ] i18n complete: all 3 locales (en, ca, es) have matching keys

4. Report Drift

Present findings in a structured table:

## Documentation Drift Report
 
| Surface | File | Issue | Severity |
|---------|------|-------|----------|
| Website | DocsContent.astro | Missing --profile flag in CLI section | High |
| SDK README | src/sdks/python/README.md | load() example uses old API | High |
| Root README | README.md | Version badge outdated | Low |
 
## Alignment Actions
 
1. {file}: {what to update}
2. {file}: {what to update}

5. Apply Fixes

For each drift item:

1. Update the documentation surface
2. If i18n strings changed, update all 3 locales
3. Verify the fix against the source of truth

6. Validate

• Run pnpm lint to check for formatting issues
• For website changes, verify the build: check i18n key consistency

Cross-Reference Matrix

Use this matrix to ensure consistency when updating a feature:

Constraints

• Never invent features not present in code
• Verify claims against source code before writing
• Preserve existing document structure and tone
• Keep code examples minimal and runnable