HoangNguyen0403 / documentation-standards
Install for your project team
Run this command in your project directory to install the skill for your entire team:
mkdir -p .claude/skills/documentation-standards && curl -L -o skill.zip "https://fastmcp.me/Skills/Download/3665" && unzip -o skill.zip -d .claude/skills/documentation-standards && rm skill.zipProject Skills
This skill will be saved in .claude/skills/documentation-standards/ and checked into git. All team members will have access to it automatically.
Important: Please verify the skill by reviewing its instructions before using it.
Essential rules for code comments, READMEs, and technical documentation.
0 views
0 installs
Skill Content
---
name: Documentation Standards
description: Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
metadata:
labels: [documentation, comments, docstrings, readme]
triggers:
keywords: [comment, docstring, readme, documentation]
---
# Documentation Standards - High-Density Standards
Essential rules for code comments, READMEs, and technical documentation.
## **Priority: P2 (MAINTENANCE)**
Essential rules for maintaining proper code comments, READMEs, and technical documentation.
## 📝 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.