[DOCS] Documentation Overhaul Action Items from Planning Call (2026-03-20)

## Context Planning call on 2026-03-20 to overhaul connector-service documentation. Goal: Make docs developer-friendly and AI-agent-ready. --- ## Action Items ### 1. Add Connector Status Legend **What:** Add a color-coded legend to connector status tables. **Colors:** - **Green (✓)**: Hardened — Production ready, tested on dev and production - **Orange**: Implemented — Code exists but not production-hardened - **Gray**: Does not exist / Not applicable **Note:** Remove separate "all connectors" file. Consolidate into two tables: (1) Connector + Operations, (2) Payment Methods. --- ### 2. README.md Overhaul **What:** Rewrite README to be concise and compelling. **Requirements:** - Max 2 pages (no scrolling on standard screen) - First two paragraphs must explain the problem: - Developers run in circles with AI agents - Months of engineering effort wasted - Payment processor docs are diverse - Actual behavior differs from specs - AI implements well only when docs are thorough **Three value propositions to state:** 1. **Stateless** — Connector library, no persistence 2. **Hardened** — Tested on dev and production, iterative bug fixing 3. **Unified** — Single interface for all payment processors **Remove:** "Building from Source" section --- ### 3. Getting Started Section **What:** Create clear onboarding path for developers. **Content:** - Installation tabs for: Python, Java, PHP, Rust, Go - "Create Payment Order" example with language tabs - Two processor examples (Stripe + Braintree) to demonstrate routing - PCI vs non-PCI compliant path guidance - Connector credentials configuration examples --- ### 4. Architecture Documentation **What:** Document the three-layer architecture. **Layers:** 1. **SDK Binding Layer** — Language-specific interfaces (Python, Java, PHP, etc.) 2. **Core Layer** — Types, adapters, request/response transformers 3. **Connector Layer** — PSP integrations (Stripe, Adyen, etc.) **Additional:** - Add sequence diagram for payment flow - Remove gRPC from external-facing docs (internal only) - Explain data flow between layers --- ### 5. Error Handling Documentation **What:** Document the three error categories. **Categories:** 1. **Unified Errors** — Business errors with standard error codes 2. **Connector Errors** — PSP-specific errors mapped to unified codes 3. **Network Errors** — Timeouts, rate limits, connection failures **Include:** - Error code mapping table (Stripe → Unified, Adyen → Unified) - Example error responses - User guidance and retry recommendations --- ### 6. Unified Error Code Mapping (TOML) **What:** Create unified error code mappings per connector. **Dependency:** Wait for Gopi's PR (error details population in ErrorInfo) **Implementation:** - Create TOML file with default unified error code mappings - Include default mappings in SDK - Allow runtime overrides via config --- ### 7. Testing Framework Documentation **What:** Document the testing framework concepts. **Three concepts:** 1. **Global Suite** — Standard test scenarios applied to every connector 2. **Scenarios** — Specific flow tests (authorize, capture, refund, etc.) 3. **Overrides** — Connector-specific test modifications **Additional:** - How to run tests locally - CI/CD integration --- ### 8. SDK Documentation Structure **What:** Mirror API reference structure for each SDK. **Per method:** - SDK method name - Request/response types - Code examples in target language (not just proto) **Note:** Fix SDK method patterns consistently (if wrong in one place, it's wrong everywhere) --- ### 9. Versioning and Releases **What:** Document versioning convention. **Convention:** - **Major** — Breaking proto changes - **Minor** — New features, new connectors - **Patch** — Bug fixes, connector updates (1.2.x auto-updates) **Recommendation:** Don't pin versions tightly --- ### 10. Code Generation Frameworks **What:** Document code generation capabilities. **Generators:** - New connector addition - SDK bindings (Python, Java, PHP, Go, Rust) - Example snippets **Location:** Move generation scripts to `/docs-generated` folder, keep handwritten docs in `/docs` --- ### 11. Environment Configuration **What:** Document environment setup options. **Content:** - Sandbox vs production URLs - Proxy configuration - HTTP transport configuration - Retry policy configuration - Idempotency settings --- ### 12. GitBook Compatibility **What:** Ensure docs render properly in GitBook. **Requirements:** - Use GitHub tabs format for language-specific content - Test navigation and cross-references - Ensure no broken links --- ## Priority Order 1. README.md overhaul (highest — first impression) 2. Getting Started section 3. Architecture documentation 4. Error handling 5. Testing framework 6. Code generation docs --- ## Related - Call date: 2026-03-20 - Transcript: Available