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)
Installs into .claude/skills of the current project.
Are you the author of Common Documentation?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/comeonoliver-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.
