I was thinking about all of this lately. Knuth's LP is useful when you present an algorithm. That's where the quantity of explanation text is much greater than

I was thinking about all of this lately. Knuth's LP is useful when you present an algorithm. That's where the quantity of explanation text is much greater than the code itself. It is also good when you describe an algorithm because it is a dynamic thing : an algorithm has to be "processed" in your mind to be understood and a good explanations might help to describe its behaviour. A notebook is good when you're doing steps to achieve a goal; but it's not good to explain an full programs I think. What would be nice is to have notebooks woven into bigger codebases. Or it would be cool to have links from notebooks directly to code, functions, methods,... for example when you just want to mention you're using a part of your code that doesn't deserve to be explained by a notebook. Also, something that would be nice is to have hierarchical notebooks. On the first level, you have a general explanation of what you do. Then you can go deeper and get more information about details of your code...