ContextQMD
Back to Cline

Documentation Skill

sdk/examples/plugins/agents-squad/skills/documentation.md

3.83.02.6 KB
Original Source

Documentation Skill

When writing or improving documentation, follow these principles:

1. Know Your Audience

  • README: New developers evaluating or onboarding to the project.
  • API docs: Developers integrating with the API.
  • Architecture docs: Team members understanding system design.
  • Inline comments: Future maintainers (including yourself in 6 months).

2. README Structure

A good README answers these questions in order:

  1. What is this? One paragraph. What problem does it solve?
  2. Quick start: The fastest path from zero to working. Copy-pasteable commands.
  3. Installation: Prerequisites, install steps, configuration.
  4. Usage: Common use cases with code examples.
  5. API reference: If small enough; otherwise link to generated docs.
  6. Configuration: All options with defaults and descriptions.
  7. Contributing: How to set up dev environment, run tests, submit changes.
  8. License: One line.

3. API Documentation

For each endpoint, function, or method:

### functionName(param1, param2, options?)

Brief description of what it does.

**Parameters:**
- `param1` (string, required) — What this parameter controls.
- `param2` (number, optional, default: 10) — What this parameter controls.
- `options.verbose` (boolean, default: false) — Enable verbose output.

**Returns:** `Promise<Result>` — Description of the return value.

**Throws:**
- `ValidationError` — When input is invalid.
- `NotFoundError` — When the resource doesn't exist.

**Example:**
```ts
const result = await functionName("input", 5);


## 4. Architecture Documentation

- Start with a high-level diagram (Mermaid, ASCII, or image).
- Describe each component's responsibility in one sentence.
- Document data flow for the most important operations.
- List key design decisions and their rationale.
- Note known limitations and planned improvements.

## 5. Inline Comments

Write comments that explain **why**, not **what**:

- ✅ `// Retry 3 times because the upstream API has transient 503s during deploys`
- ❌ `// Retry 3 times`
- ✅ `// Sort descending so the most recent entry is first for the dashboard`
- ❌ `// Sort the array`

Never comment obvious code. If code needs a comment to explain what it does, refactor the code to be self-explanatory first.

## 6. Quality Checklist

Before finalizing documentation:
- [ ] All code examples compile and run.
- [ ] No broken links.
- [ ] Consistent formatting and terminology.
- [ ] No outdated information from previous versions.
- [ ] Spelling and grammar checked.
- [ ] Table of contents for documents longer than 3 sections.