channinghe/documentation

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

// ✅ 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.md

Content:

Payment Flow Module

Handles Stripe payment intent creation and callback verification. Core based on PaymentIntent state machine.

Usage

...

Edge Cases

• ⚠️ Doesn't support transactions below 0.50 USD
• Webhooks may be resent, must ensure idempotent handling