documentationlisted

# Documentation Standards ## Core Principle "Code tells you how; Comments tell you why; Docs tell you how to use." Documentation is not a dev diary; it's a user manual for future maintainers. ## Trigger Conditions - **✅ Must create**: Completed a full Feature module, introduced new architecture pattern, or added new public API - **❌ Forbidden**: Just fixed a bug, refactored internal private method, or adjusted styles. Don't pollute `/docs/` with fragmented docs ## File Path & Naming - **Path**: `/docs/specs/` - **Naming**: `{feature-name}.md` (use kebab-case, e.g., `user-authentication.md`) ## Documentation Structure Template Documentation must be concise and powerful, strictly following: ### 1. Core Concept - One sentence explaining what this module does - *Linus perspective*: What's its core data structure? ### 2. Data Flow (optional) - Use Mermaid flowchart or text to describe data flow path - What's the input? What's the output? Who holds state? ### 3. Usage Guide - **Show, don't tell.** Less talk, more code - Provide 1-2 **Minimal Working Examples** ```javascript // ✅ Correct usage example const user = await authService.login(credentials); ``` ### 4. Edge Cases - When will this module crash? - What are known limitations? (e.g., concurrency cap, unsupported file types) ### 5. Maintainer Notes - If you're the architect, what do you want the successor to know? - Any non-intuitive design decision rationales ## Example **File**: `/docs/specs/payment-flow.