I think most of us approach documentation without intention. We write to express the idea, but fail to consider how the documentation fits into the deliverable.

For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an implementation detail.

I think software as a discipline is distinctly undiscipled about these sorts of concepts.

Sure. But where some see the lack of updates as some sort of moral failure, I think it's usually a sign that there is a process problem. The documentation was supposed to solve some sort of problem, but the fact that people don't update it is usually a sign that either it wasn't a real problem, that documentation wasn't the right solution, or that there's a broken feedback loop in the team's process.

I built this documentation/testing framework to do just that: https://hitchdev.com/hitchstory

I realized one day that the specs, tests and how-to markdown documentation I wrote all used the same examples.

From that I derived the idea to create a "spec" DSL that could both be run as a test and generate markdown (with screenshots, etc.) to make nice high level how-tos.

Cucumber has the same sort of idea but the DSL really isn't suitable.