[yourapostasy]

That was the premise of literate programming: interweave the docs with the code, and developers would find it frictionless to keep the docs updated.

The challenge I ran into is scaling it up. There isn’t an “aspect-oriented, single source multiple output literate programming” implementation yet. So if you were a developer, you see the code and code docs. If you were new to the codebase, then you could switch to an “architecture” aspect or “design” aspect, and see different docs that still link back to relevant code blocks. If you were a technical writer maintaining user docs, you would switch to a “user manual aspect” that still linked back to relevant code blocks. Same for operations manager, support team member, and so on.

We do this linking back all by hand today, and the mental model people build up in their heads and across a Net-mediated consensus to establish the link mostly evaporates when the issue at hand is addressed. I wouldn’t B&D require linkage, but it sure would be nice to have memorialize linkages for specific issues, discussions, and so on.

We express most of the metadata today, there isn’t a system I’ve found yet that captures it in a low-friction manner.

[hinkley]

I was able to link docs with functional tests at one point. That made more sense and it scaled to a degree. You definitely need a way to include or exclude chunks of tests from code examples, because the bootstrapping in tests doesn’t match production code very often.