playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / documentation

documentation skill

/skills/common/documentation

This skill enforces documentation standards for comments, READMEs, and APIs to improve clarity, maintenance, and collaboration.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill documentation

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: Documentation Standards
description: Essential rules for code comments, READMEs, and technical 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.

Overview

This skill defines essential rules for code comments, READMEs, and technical documentation to keep projects maintainable and discoverable. It focuses on clear intent in comments, structured README content, and robust API and architectural documentation. The guidance applies across languages and frameworks to standardize developer expectations.

How this skill works

The skill inspects code comments, docstrings, README sections, ADRs, and API specs to ensure they follow concise standards: explain intent, include precise prerequisites and examples, and keep docs synchronized with code. It flags commented-out code, missing ownership on TODOs, absent API examples, and lack of architectural records. It also recommends generators like OpenAPI/Swagger and diagram usage for high-level overviews.

When to use it

  • When adding or modifying public functions, classes, or endpoints.
  • During code reviews to enforce comment intent and doc completeness.
  • When creating or updating project READMEs and onboarding docs.
  • Before shipping APIs to ensure contract and example coverage.
  • While making architectural changes that require rationale and traceability.

Best practices

  • Prefer explaining the "why" in comments; let code show the "what".
  • Use formal docstrings/JSDoc for public APIs and include Args, Returns, and usage examples.
  • Remove commented-out code; rely on version control for history.
  • Tag technical debt with TODO(username): description or FIXME and assign ownership.
  • Keep README focused: one-line mission, prerequisites, install, usage, and troubleshooting.
  • Use ADRs for major decisions and include Mermaid diagrams for system context.

Example use cases

  • A developer documents a public TypeScript class with JSDoc including examples and edge cases.
  • During a review, the agent flags commented-out blocks and missing TODO owners.
  • A team writes an ADR describing a database migration decision and links a Mermaid sequence diagram.
  • API endpoints are documented with OpenAPI and include copy-paste curl and client examples.
  • The README is updated alongside a feature to add exact runtime prerequisites and troubleshooting steps.

FAQ

Should comments repeat what code already expresses?

No. Comments should explain intent, rationale, or non-obvious trade-offs. If code is unclear, refactor rather than verbose commenting.

When is a TODO acceptable in code?

Use TODO(username): description or FIXME only for tracked, time-bound technical debt with clear ownership and expected removal conditions. Avoid vague or permanent TODOs.