# Documentation Standards

> Essential rules for code comments, READMEs, and technical documentation.

- Skill: `mte90/documentation-standards` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mte90/documentation-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mte90/documentation-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mte90 (https://skillmd.com/u/mte90)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mte90/documentation-standards

---


# 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.