maintaining-documentation

A coding-agent skill for writing documentation people can use, and keeping it true over time. It writes READMEs, tutorials, how-to guides, troubleshooting guides, reference, and architecture docs for the reader who will open them, instead of narrating the code. It audits docs against the code, updates the docs that ride along with a code change, maintains a project terminology dictionary, and decides where new docs belong. It refuses to rewrite historical records like design specs and plans just because the code moved on.

Installation

Native integration files and installation guides are generated with everyharness from everyharness.yaml.

See the support matrix for what each harness supports.

Using it

The skill triggers on its own when a task involves docs. You can also ask for it directly:

People keep asking why image paste fails over SSH. Write a troubleshooting doc.

Audit the docs in this repo against the code.

I just finished this branch. Update the docs that cover what I changed.

Where should a doc about the new retry policy live?

Set up a terminology dictionary for this project.

When it writes a doc, the agent first pins down who the reader is, what brought them to the doc, and what they need to get done. It picks the doc type that fits that job, writes in the reader's vocabulary rather than the code's, and then hands the draft to a fresh agent playing that reader, with no access to the code, to find where they get stuck. Last, it copyedits the prose with Strunk's The Elements of Style and checks that the copyedit didn't change what any sentence claims.

The plugin ships a second skill, copyediting-docs, which does that copyedit and drift check. It carries The Elements of Style (1918), cut down to what applies to technical docs. You can also use it on its own:

Copyedit docs/ARCHITECTURE.md.

On first use in a project, the agent proposes which docs are evergreen (must match current reality: README, guides, reference) and which are point-in-time (true as of their date: specs, plans, design notes). It asks you to confirm before editing anything. That classification is saved in a doc index so later runs don't ask again.

What it adds to your project

At most two files, plus a one-line stamp at the end of each verified doc:

• docs/DICTIONARY.md: the project's canonical terms and their deprecated synonyms.
• A doc index table, in docs/README.md (or docs/INDEX.md if there is no docs README), recording each doc's class and the code paths it covers.

The agent leaves its edits uncommitted for you to review.

The docmaint helper

The skill bundles skills/maintaining-documentation/scripts/docmaint, a stdlib-only Python 3 tool the agent uses for the mechanical parts:

python3 skills/maintaining-documentation/scripts/docmaint --help
python3 skills/maintaining-documentation/scripts/docmaint scan  --root /path/to/repo
python3 skills/maintaining-documentation/scripts/docmaint stale --root /path/to/repo

scan finds deprecated terms, stamp reads or writes last-reviewed stamps, and stale lists docs whose code changed since they were last verified. It never edits doc prose.

Requirements: Python 3.10+ and Git.

Development

python3 skills/maintaining-documentation/scripts/docmaint_test.py  # helper tests
npx everyharness generate   # after editing everyharness.yaml or skills
npx everyharness validate

evals/ holds the doc-writing scenarios used to test changes to the skill: real repos with one doc removed, and a blind judge that plays the doc's reader. See evals/scenarios.md.

Generated harness files are committed. Edit everyharness.yaml and the skill, then regenerate; don't hand-edit generated files.

License

MIT, except skills/copyediting-docs/elements-of-style.md: William Strunk Jr.'s The Elements of Style (1918), public domain, abridged from Project Gutenberg #37134.