402 Deletions, Zero Additions: Fixing Etro's Docs by Deleting Them

Not every open-source contribution adds a feature. Some of the most satisfying ones take something away. This is the story of a pull request to Etro — a TypeScript library for programmatic video editing in the browser — where the entire diff was 402 deletions and zero additions, and that was exactly the right fix.

The bug: docs that wouldn't build

Issue #349 was short and ominous:

Running npm run doc results in build errors. This could break the build for the site, which depends on these docs.

A broken documentation build is the kind of bug that quietly rots. It doesn't crash anyone's app, so it sits ignored — until a release or a docs deploy trips over it. I picked it up, got myself assigned, and started with the most boring, most important step: reproduce it.

npm run doc
# 💥 build errors

Confirmed. Now the interesting question: why?

The investigation: a half-finished migration

Here's the script the issue was complaining about, straight from package.json:

"doc": "rm -rf docs && npx typedoc src/etro.ts --excludePrivate --readme none"

So the script used TypeDoc. But sitting right next to it in the repo was this file, jsdoc.conf.json:

{
  "plugins": ["../node_modules/jsdoc-export-default-interop/dist/index"]
}

That's a JSDoc config. And in devDependencies I found docdash — a JSDoc theme — installed right alongside typedoc.

Two different documentation toolchains, tangled together. The repo had clearly migrated from JSDoc to TypeDoc at some point, but nobody swept up the JSDoc leftovers. The config pointed at a tool the script didn't even use anymore.

But the real revelation came when I went looking for where these generated docs actually went. The answer: nowhere anyone used. Etro's documentation site is maintained in a completely separate repository, etro-js.github.io. The local npm run doc pipeline was orphaned — a build step wired to nothing.

The decision: fix it, or delete it?

This is the fork in the road that makes cleanup PRs interesting. I could have spent an afternoon debugging TypeDoc versions and config until npm run doc produced HTML again. But that would have been polishing a step whose output no one consumes.

The right question wasn't "how do I make this build?" — it was "should this exist at all?" And once I confirmed the docs live elsewhere, the answer was clearly no.

The best fix for dead code isn't repair. It's deletion.

The fix

The PR (#359, chore: remove jsdoc config and doc generation script) did four things:

1. Deleted jsdoc.conf.json — the orphaned JSDoc config.

2. Removed the doc script from package.json.

3. Removed docdash and typedoc from devDependencies — nothing else referenced them, so they were pure dead weight (and 395 lines of package-lock.json went with them).

4. Updated AGENTS.md, deleting the npm run doc row from the contributor command table so the docs wouldn't lie about a command that no longer exists.

The full damage:

 AGENTS.md         |   1 -
 jsdoc.conf.json   |   3 -
 package-lock.json | 395 ------------------------------------------------------
 package.json      |   3 -
 4 files changed, 402 deletions(-)

Merged. Issue closed. The repo got lighter, the broken build step is gone, and a future contributor won't waste an hour wondering why npm run doc explodes.

Best practices I followed

A four-file deletion sounds trivial, but the approach is where the craft lives. Here's what I'd carry into any contribution:

• Reproduce before you fix. I ran npm run doc and saw the failure with my own eyes before touching anything. Never fix a bug you haven't confirmed.

• Find the root cause, not the symptom. The symptom was "build errors." The root cause was "this tooling is orphaned." Chasing the symptom would have wasted time repairing something no one needed.

• Question the premise. The obvious task was "fix the doc build." The correct task was "delete the doc build." The most valuable thing you can do with a broken feature is ask whether it should exist at all.

• Delete completely — leave no orphans. I didn't just remove the script; I pulled its config file, its dependencies, and its lockfile entries too. Half-removals are how you create the next issue #349.

• Keep docs in sync with code. The AGENTS.md command table referenced npm run doc. Removing the command without updating the docs would leave a lie behind for the next contributor.

• Keep the PR atomic. One concern: remove dead doc tooling. No drive-by refactors, no unrelated tweaks. Small, single-purpose PRs are the ones maintainers merge quickly.

• Write a commit that explains why. The message didn't just say "remove jsdoc." It listed each change and, crucially, the reason: docs are maintained in the separate etro-js.github.io repo. Future-me — and every reviewer — gets the context for free.

• Link the issue. Closes #349 in the PR body auto-links the two and closes the issue on merge — no manual bookkeeping.

• Respect the project's conventions. Etro uses Conventional Commits and gitmoji; the change went out as chore: and merged as 🔥 Remove jsdoc and doc generation script. Match the house style — it's the maintainer's repo, not yours.

Sometimes the best code you'll write is the code you delete. 🔥