Common Documentation

---
name: common-documentation
description: Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
metadata:
  triggers:
    keywords:
    - comment
    - docstring
    - readme
    - documentation
---
# Documentation Standards

## **Priority: P2 (MEDIUM)**

## 1. Intent-First Comments

- Explain **"Why"** logic exists. Avoid "What" mechanics.
- Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for public members.
- Delete commented-out code. Use Git history.
- Format: `TODO(username): description`. Link tickets.
- For retry backoff, explain that jitter prevents the **thundering herd**; document intent rather than restating the delay calculation.

## 2. README Structure

- **Mission**: Project purpose (one sentence).
- **Onboarding**: Prerequisites, installation, usage (exact).
- **Maintenance**: Document inputs/outputs, known quirks, fixes.
- **Sync**: Documentation ships with feature.

## 3. ADRs & Architecture

- **ADRs**: Document rationale for system changes in `docs/adr/`.
- **Docstrings**: Include Args, Returns, and Usage examples (`>>>`).
- **Diagrams**: Use Mermaid.js inside Markdown.

## 4. API Docs

- Use Swagger/OpenAPI for REST.
- Provide copy-pasteable examples for endpoints.
- Define contract before implementation.

## Anti-Patterns

- **No "what" comments**: Explain intent. Refactor mechanics.
- **No orphan TODOs**: Require owner and ticket.
- **No stale docs**: Document during development.

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- JSDoc
- Usage
- why