← ClaudeAtlas

occam-docslisted

Writing or updating code documentation, such as a README, API reference, guide, docstrings or changelog, especially for code just written. Checks claims with the occam tools, runs the examples, then hands the prose to human-voice if installed. Use alongside occam.
stephenoffer/occam · ★ 1 · Code & Development · score 74
Install: claude install-skill stephenoffer/occam
# Documenting code Documentation written straight after the code tends to describe what the author meant to build, in a voice nobody uses. Facts come first, because a well-written wrong claim costs a reader more than a clumsy right one, and a rewrite for voice is when facts slip. That is why the steps run in this order. Write what the request or the repository calls for. A small fix updates the sentence it made wrong and doesn't earn a new guide. `occam` below means `python3 ../occam/scripts/occam.py`, relative to this skill. ## Order 1. **Reader and scope.** Who reads this, and what are they trying to do? Extend the documents already here and follow their layout before adding one. 2. **Facts from the code.** Read the code as it is now, not the plan, the commit message or your memory of writing it: entry points, public names and signatures, flags and defaults, configuration keys, environment variables, errors and side effects. Keep a list with file and line. Capture real output from `--help` and from running it. Where code and intent disagree, that is a defect to report, not a sentence to write. 3. **Claims the evidence supports.** "Fast", "secure", "production ready" and "supports X" each need a test or measurement you have, with its scope. Say what is untested. Don't document a path nothing reaches, and don't invent output, benchmarks or versions. A breaking change's entry says what breaks, for whom, and the old-to-new steps, with an example you ran. A runbook's command