Documentation Generation

Overview

Bad documentation is worse than no documentation. Stale docs actively mislead. Docs that restate what the code says add noise without signal. Docs without examples are reference manuals nobody reads.

Core principle: Documentation describes INTENT and CONTRACTS, not implementation details. The code shows what happens. The docs explain why it matters and how to use it.

If your docs require updating every time you refactor internals, you're documenting the wrong thing.

Announce at start: "I'm using the documentation-generation skill to create this documentation."

The Iron Law

DOCUMENTATION DESCRIBES INTENT AND CONTRACTS, NOT IMPLEMENTATION DETAILS

If a doc would become stale from an internal refactor that doesn't change behavior, that doc is wrong. Rewrite it to describe the contract, not the mechanism.