Common Documentation

3. Maintain Architectural Docs

• ADRs: Document significant architectural changes and the "Why" in docs/adr/.
• Docstrings: Document Classes/Functions with Args, Returns, and usage Examples (>>>).
• Diagrams: Use Mermaid.js inside Markdown for high-level system overviews.

4. Document APIs

• Use Swagger/OpenAPI for REST or specialized doc generators.
• Provide copy-pasteable examples for every major endpoint.
• Define the interface contract before the implementation.

Anti-Patterns

• No "what" comments: Explain intent, not mechanics. Refactor instead.
• No orphan TODOs: Every TODO needs (owner) and a linked ticket.
• No stale docs: Documentation ships with the feature, not after.