---
title: "Discussion on \"I Built docproof: a CLI That Tests Your Documentation by Running It\" | Hashnode"
description: "Discussion on \"I Built docproof: a CLI That Tests Your Documentation by Running It\". Your README is code that never gets executed. I built a small CLI that runs it, fails your build when the docs are broken, and asks Claude how to fix them."
url: "https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba"
---

[Feed](https://hashnode.com/feed) /

Discussion

# [I Built docproof: a CLI That Tests Your Documentation by Running It](https://blog.ipseeta.dev/docproof-test-your-docs-by-running-them?utm_source=hashnode&utm_medium=feed)

Your README is code that never gets executed. I built a small CLI that runs it, fails your build when the docs are broken, and asks Claude how to fix them.

Aug 6 · 7 min read · blog.ipseeta.dev  
Updated Nov 4  
Read the article

-   [#typescript](https://hashnode.com/tag/typescript)
-   [#nodejs](https://hashnode.com/tag/nodejs)
-   [#cli](https://hashnode.com/tag/cli)
-   [#documentation](https://hashnode.com/tag/documentation)
-   [#testing](https://hashnode.com/tag/testing)
-   [#opensource](https://hashnode.com/tag/opensource)

## Written by

[Ipseeta Priyadarshini](https://hashnode.com/@ipseeta)

@ipseeta · India

  
[View profile](https://hashnode.com/@ipseeta)

Software Developer @Bug0 | @Hashnode, Contributing writer to The Foreword by Hashnode

Full-Stack Developer @ Bug0 | Node.js, Next.js, JavaScript, TypeScript | Ex-Wipro, DXC, Majesco/Mastek | ex-Java, ex-Spring

## Responses 7

Markdown supported · ⌘↵ to post

[Henry Robt](https://hashnode.com/@henryrober)

[Aug 8](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a76c6dc554ae58ec65ce558)

This is a really practical idea. Documentation can easily become outdated when commands or APIs change, so actually running the code examples is a much better check than reviewing the README manually. The CI integration also makes it especially useful for keeping documentation reliable over time.

[Duko tools](https://hashnode.com/@talha24ramzan)

[Aug 7](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a75992b1fa1f0f3ad2ad5dd)

"Documentation is code that hasn't been executed" is the reframe that makes this whole tool obvious in hindsight, every other artifact in a repo gets a CI check the moment it can be automated, and the README was exempt purely because nobody built the runner, not because it mattered less.

The skip-directive design is the part I'd point to as the actual engineering insight, not the extraction/execution pipeline. A doc-testing tool that fails on every install command or credentialed API call would get disabled within a week, so the real work was building an escape hatch precise enough that "illustrative by design" and "actually broken" stay distinguishable, and the AI prompt explicitly being told "suggest a skip directive" instead of forcibly rewriting unrunnable samples is the same insight applied one layer up.

Sequential-shared-workspace-per-file over parallel execution is a good example of resisting the more impressive-sounding default. Parallel would demo well and be structurally wrong the moment a doc has a "create config, then read config" pattern, which is most real tutorials, matching execution order to how people actually write docs mattered more than raw throughput here.

[Ipseeta Priyadarshini](https://hashnode.com/@ipseeta)

[Aug 7](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a75992b1fa1f0f3ad2ad5dd#reply-6a75aa2d000c300767b2f38c)

Thank you for reading it this closely, you've articulated the skip-directive thinking better than I did in the post. :)

[Puneet Khandelwal](https://hashnode.com/@lifestyle4u)

[Aug 6](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a7487ede6e32d7eecfad7ca)

LLove this perspective - it really makes me think about my priorities.

[Ipseeta Priyadarshini](https://hashnode.com/@ipseeta)

[Aug 7](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a7487ede6e32d7eecfad7ca#reply-6a75aa76fb214d1a1b2a8edd)

Thank you, glad it resonated!

[Chloe Dumont](https://hashnode.com/@chloe_sec)

[Aug 6](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a747a3404dc832a84e0bff9)

Nice article!

[Ipseeta Priyadarshini](https://hashnode.com/@ipseeta)

[Aug 6](https://hashnode.com/posts/docproof-test-your-docs-by-running-them/6a7475850190836b666799ba/comment/6a747a3404dc832a84e0bff9#reply-6a747a9c36efaea43e48a747)

If you run docproof on your README and it catches something broken, I'd genuinely love to see it!