[hitchstory]

I built a testing and documentation framework to solve precisely this problem (google for my username to find it).

You write the StrictYAML based tests structured according to your domain language/interactions and then you write one class that interprets them to execute the test and one template file that you apply to generate the markdown/HTML/whatever docs (with test artifacts like screenshots if you want them).

How to documentation then becomes a build artefact that, since it is generated from a test, never goes out of date by definition.

I usually combine this kind of docs with other types (e.g. explanatory) which can't be generated but also dont tend to go out of date.