> I was thinking of doing something like this, but you have an even better idea here. Actual references back to the code. I might start trying to do that.

Literate programming (in the Knuth sense): yay!

> (Though that's probably as much work, if not more, as writing the software ;)

Yep. Hence one of the few big projects I'm aware of that use lp (apart from Knuth) is:

Axiom:

http://axiom.axiom-developer.org/axiom-website/books.html

Ed: from the post: > (And writing this post helped uncover a bug, so even if no one reads this, it was worth it).

Literate programming: yay!

Or perhaps narrative-driven design: ndd, to go with tdd and bdd...