Skip to content

Instantly share code, notes, and snippets.

@0atman
Last active June 2, 2024 17:01
Show Gist options
  • Save 0atman/242cf9d6d99f2fbeb182a090213cf74a to your computer and use it in GitHub Desktop.
Save 0atman/242cf9d6d99f2fbeb182a090213cf74a to your computer and use it in GitHub Desktop.
The Testable Documentation Manifesto

#! blaze sh

The Testable Documentation Manifesto

One of the problems with tech documentation (api, installation instructions etc) is that they get stale. APIs change, software and plugins alter their interface and commands, and websites go away.

To solve this, I propose we write our documentation in a way that can be executed, or verified.

Luckily, I wrote blaze to execute codeblocks inside of markdown, which means that with a little help from a few common unix tools, we can solve this problem.

Testable Software Installation Example

set -e
pip install badpackage_123183183

The output of executing the very file you are reading now is:

$ ./README.md

Collecting badpackage_123183183

Could not find a version that satisfies the requirement badpackage_123183183 (from versions: ) No matching distribution found for badpackage_123183183

You now can execute your readme instructions as part of your build process (perhaps with a little setup beforehand, such as running it inside a container), and the exit code (in this case 1) will allow you to fail the build if the instructions are out of date.

For more information: github.com/0atman/blaze

@correabuscar
Copy link

the README.python.md link is 404

@crabdancing
Copy link

@correabuscar

They should add a feature to test URLs :P

Although, to be fair, it probably broke after test execution.

@InDieTasten
Copy link

InDieTasten commented Oct 6, 2023

@correabuscar @alxpettit Tris moved this into a separate repo which now has a bunch more examples: https://github.com/0atman/blaze

@0atman Maybe edit this gist to something that directs users to the new repo like you did here: https://gist.github.com/0atman/5ea526a3ae26409da50dd7697eb700e8

@0atman
Copy link
Author

0atman commented Oct 13, 2023

Many thanks, added the blaze link!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment