Documentation and automated tests belong together. It makes tests better. Instead of a shady snippet of code that just passes an assertion, it should generate

Documentation and automated tests belong together. It makes tests better. Instead of a shady snippet of code that just passes an assertion, it should generate human readable examples with additional prose included by the developer for special cases. It makes docs easier to maintain. You probably already need to find the test for the code you changed. If the docs are really close, it's easier to maintain it. There are many ways of achieving this. I particularly like literate programming, just for the test suite. You can code whatever way you like, but the tests must be in a literate form. I also like the idea of having a documentation that can fail a build. If you commit a bad example snippet on a markdown somewhere, the CI should fail. This can already be done with clitest, for example (scaling it culturally is a bit hard though). Somehow, xUnit-like tools and spec frameworks already point in that direction (DSLs that embrace human language, messages in assertions, etc). They're already documentation, and developers already use test suites for "knowing how something works" very often. We just need to stop writing it twice (once on the tests, once on prose) and find a common ground that can serve both purposes. I mean this for API docs mainly, but for other stuff as well.