# Documentation Standards > Essential rules for code comments, READMEs, and technical documentation. Use when this capability is needed. - Skill: `tomevault-io/documentation-standards-18` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/documentation-standards-18` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-standards-18/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/documentation-standards-18 --- # 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. ## 📖 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. --- > Source: [fierzone/agent-skills-standard](https://github.com/fierzone/agent-skills-standard) — distributed by [TomeVault](https://tomevault.io).