I like Tim Daly's viewpoint that we shouldn't just be writing code, but we should write manuals - giving high level overviews of our problems and specifying their implementation details inside the manuals. His talk "Literate Programming in the Large"[1] covers why.
The example he gives in his talk is the Axiom algebra system[2], which was revised to use literate programming style - the source code, with usage examples, is contained entirely within the books.
The example he gives in his talk is the Axiom algebra system[2], which was revised to use literate programming style - the source code, with usage examples, is contained entirely within the books.
[1]:https://www.youtube.com/watch?v=Av0PQDVTP4A, [sldes]: http://daly.axiom-developer.org/TimothyDaly_files/publicatio...
[2]:https://en.wikipedia.org/wiki/Axiom_%28computer_algebra_syst...