This is kind of what I have been doing with this testing framework: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory It's designed

This is kind of what I have been doing with this testing framework: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory It's designed so that you can write tests that are the basis of the "how to" documentation - with a small script and some jinja2 you can generate readable documentation in the form of markdown from the test: Original test (behavioral example) : https://github.com/crdoconnor/strictyaml/blob/master/hitch/story/email-url.story https://github.com/crdoconnor/strictyaml/blob/master/hitch/s... Example docs generated from that test : https://hitchdev.com/strictyaml/using/alpha/scalar/email-and-url/ https://hitchdev.com/strictyaml/using/alpha/scalar/email-and... It's also designed so that the testing framework can be programmed to rewrite the test automatically for simple code changes (e.g. changing the wording of that exception). This makes building tests much quicker and much, much less tedious and perfectly in sync docs almost becomes a side effect. Essentially "how to" documentation and example driven behavioral tests are the same thing for all projects. It's just that most people don't realize and don't treat them as such.