common-documentation

Documentation Standards

Priority: P2 (MAINTENANCE)

? Code Comments (Inline Docs)

• "Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
• Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
• Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
• TODOs: Use TODO(username): description or FIXME to track technical debt with ownership.
• Workarounds: Document hacks and removal conditions (e.g., backend bug, version target).
• Performance Notes: Explain trade-offs only when performance-driven changes are made.

? README Essentials

• Mission: Clear one-sentence summary of the project purpose.
• Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
• Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
• Up-to-Date: Documentation is part of the feature; keep it synchronized with code changes.

? Architectural & API Docs

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

? API Documentation

• Self-Documenting: Use Swagger/OpenAPI for REST or specialized doc generators for your language.
• Examples: Provide copy-pasteable examples for every major endpoint or utility.
• Contract First: Define the interface 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 out-of-date docs: Documentation ships with the feature, not after.