Imagine this: instead of reading other people’s code and then trying to parse their intentions form [sic] it, you read the documentation to understand their intentions and then you read the code. You no longer have to strain yourself trying to understand what someone wrote for another audience (the machine). They’ve already explained it for you.

The best implementation of this I’m aware of is the Entangled bi-directional tangler. A tangler extracts code from your documentation and distributes it across the appropriate source code files. It’s [sic] bidirectionality means you can use it to write code embedded in documentation, but then also edit that code normally which it then propagates back into the code blocks in the documentation. This allows programmers to use existing tooling for testing, refactoring, and code formatting without special support for literate programming.

The best built-in implementation for this that I’ve seen is Rust’s doctests. You write a block of code in your documentation. Then you run cargo test. The code gets compiled and executed as part of your tests, and panics get reported as failures. You can also mark code blocks as should_panic, compile_fail, ignore, etc if needed.

I’d love to see tools like this in other languages. Write the docs next to the code, but compile the docs as well and make sure they actually work. This is sort of what Entangled seems to do, but ideally more entangled with the build process.