Common Documentation

---
name: common-documentation
description: "Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation. (triggers: comment, docstring, readme, 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.