Package-level Documentation Strategy¶

## Dependencies

| Direction | Package | Purpose |
|-----------|---------|---------|
| Uses → | `leetcode_datasource` | Problem metadata |
| Uses → | `<other package>` | Reason |

> ❗ **Do NOT list tools here.** Tools depend on packages, not vice versa.

## Related Documentation

- **[Complete Specification](../../docs/packages/<pkg>/README.md)** - System-level documentation

---

## Documentation Maintenance

⚠️ **When modifying this package:**

1. Update this README (quick reference)
2. Update `docs/packages/<pkg>/README.md` (complete specification)

3.4 Explicitly Forbidden Content¶

The following MUST NOT appear in Package README:

4. Docs README Specification¶

Location: docs/packages/<pkg>/README.md (or docs/runner/README.md)

ℹ️ Why docs/runner/ NOT docs/packages/runner/? - runner/ is at repo root, not under packages/ - Docs structure mirrors code structure - Only packages/<pkg>/ → docs/packages/<pkg>/

4.1 Role¶

• System-oriented
• Architecture documentation
• Explains "why this exists"
• Describes interactions with other modules
• Documents design decisions and boundaries

4.2 Language¶

English primarily (英文為主)

May include Traditional Chinese notes in specific sections (e.g., Design Notes, Pitfalls) following the runner/ style.

4.3 Recommended Structure¶

# <Package Name>

> **Status**: Canonical Reference  
> **Scope**: `<pkg>/` - <one-line description>  
> **Related**: [Package README](https://github.com/lufftw/neetcode/blob/main/packages/<pkg>/README.md)

<Overview paragraph: why this module exists and what problem it solves>

---

## Overview

Expanded description of the module's purpose and place in the system.

## Scope

### What this module handles

- Responsibility 1
- Responsibility 2

### What this module explicitly avoids

- Non-responsibility 1 (handled by `<other>`)

## Interfaces

High-level summary of public APIs. Do NOT duplicate full API docs here.

| Interface | Purpose |
|-----------|---------|
| `main_function()` | Primary entry point |
| `HelperClass` | Supporting functionality |

## How It Fits in the System

| Module | Relationship |
|--------|--------------|
| `leetcode_datasource` | Provides problem metadata |
| `runner` | Executes generated solutions |

## Typical Workflows

### Workflow: <Name>

1. Step 1 description
2. Step 2 description
3. Step 3 description

> **Note:** Describe internal/system workflows, not user CLI flows.

## Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| Stateless design | Enables parallel execution |
| Single Source of Truth | `solutions/` as canonical location |

## Failure Modes and Constraints

| Constraint | Behavior |
|------------|----------|
| Missing dependency | Raises `ConfigError` |
| Invalid input | Returns empty result |

## Related Documentation

| Document | Content |
|----------|---------|
| [Package README](../../packages/<pkg>/README.md) | Quick reference, API |
| [Solution Contract](../contracts/solution-contract.md) | File format requirements |

4.4 Explicitly Forbidden Content¶

5. Relationship with runner/¶

The runner/ module is the reference implementation for this documentation strategy:

What "Reference runner/" Means¶

✅ Style reference: - Clear responsibility definition - Clear non-responsibility statements - README not polluted by tools

❌ NOT a structural reference: - Does not mean packages should mirror runner's directory structure - Does not imply dependency inversion

6. Anti-patterns¶

❌ Anti-pattern 1: Mentioning tools in package docs¶

<!-- BAD -->
## Used By
- `tools/codegen-cli` calls this package

<!-- GOOD -->
## Dependencies
| Direction | Package | Purpose |
|-----------|---------|---------|
| Uses → | `leetcode_datasource` | Problem data |

❌ Anti-pattern 2: Duplicating content between layers¶

<!-- BAD: Same content in both files -->
src/codegen/README.md: "## How It Works: Step 1, Step 2..."
docs/packages/codegen/README.md: "## How It Works: Step 1, Step 2..."

<!-- GOOD: Different perspectives -->
src/codegen/README.md: "## Public API" (what to call)
docs/packages/codegen/README.md: "## Typical Workflows" (system-level flow)

❌ Anti-pattern 3: Scattered package docs at docs root¶

<!-- BAD: Package docs at docs/ root -->
docs/codegen.md
docs/leetcode_datasource.md

<!-- GOOD: Package docs under docs/packages/ -->
docs/packages/codegen/README.md
docs/packages/leetcode_datasource/README.md

❌ Anti-pattern 4: Writing CLI docs in package README¶

<!-- BAD -->
## Usage
```bash
python -m tools.codegen --problem 1

Public API¶

from codegen import generate_reference_skeleton
generate_reference_skeleton(problem_id=1)

Summary¶

Related Documents¶

Appendix: Migration Notes¶

When migrating existing documentation to this dual-layer structure:

1. Identify API-heavy content → Move to Package README (packages/<pkg>/README.md)
2. Identify system context → Keep/move to Docs README (docs/packages/<pkg>/README.md)
3. Chinese content → Gradually convert to English primarily; Chinese notes acceptable in specific sections
4. Avoid duplication → Each layer serves a different audience and purpose