Documentation

Follow writing-voice for tone.

Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.

Folder READMEs

Primary job: explain why this folder exists and the mental model.

Can Include

• ASCII art diagrams for complex relationships
• Overview of key exports or entry points
• Brief file descriptions IF they add context beyond the filename
• Relationships to other folders

Avoid

• Exhaustive file listings that just duplicate ls
• Descriptions that repeat the filename ("auth.ts - authentication")
• Implementation details better expressed in code

Good

markdown
1# Converters
2
3Transform field schemas into format-specific representations.
4
5```
6┌─────────────┐     ┌──────────────┐
7│ Field Schema│────▶│  to-arktype  │────▶ Runtime validation
8└─────────────┘     ├──────────────┤
9                    │  to-drizzle  │────▶ SQLite columns
10                    └──────────────┘
11```
12
13Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.

Bad

markdown
1# Converters
2
3- `to-arktype.ts` - Converts to ArkType
4- `to-drizzle.ts` - Converts to Drizzle
5- `index.ts` - Exports

The bad example just lists files without explaining the pattern or when to add new converters.

JSDoc Comments

JSDoc explains when and why to use something, not just what it does.

Good

typescript
1/**
2 * Get all table helpers as an array.
3 *
4 * Useful for providers and indexes that need to iterate over all tables.
5 * Returns only the table helpers, excluding utility methods like `clearAll`.
6 *
7 * @example
8 * ```typescript
9 * for (const table of tables.defined()) {
10 *   console.log(table.name, table.count());
11 * }
12 * ```
13 */
14defined() { ... }

Bad

typescript
1/** Returns all table helpers as an array. */
2defined() { ... }

Rules

• Include @example blocks with realistic usage
• Explain WHEN to use it, not just WHAT it does
• Document non-obvious behavior or edge cases
• Public APIs get detailed docs; internal helpers can be minimal

Code Comments

Comments explain why, not what.

Good

typescript
1// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
2// Use timestamps from the entries themselves for deterministic sorting.
3const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

Bad

typescript
1// Sort the entries
2const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

Rules

• If the code is clear, don't comment it
• Comment the "why" when it's not obvious
• Comment workarounds with links to issues/docs
• Delete commented-out code; that's what git is for