Literate programming: presenting code in human order
Peter Norvig&#x27;s comment hits the nail on the head for me:<p>&quot;
Peter Norvig
6 July 2016 at 11:47
I think the problem with Literate Programming is that assumes there is a single best order of presentation of the explanation. I agree that the order imposed by the compiler is not always best, but different readers have different purposes. You don’t read documentation like a novel, cover to cover. You read the parts that you need for the task(s) you want to do now. What would be ideal is a tool to help construct such paths for each reader, just-in-time; not a tool that makes the author choose a single pth for all readers.&quot;<p>Has anyone attempted something like this?<p>I&#x27;ve heard you can do transclusion in org-mode which might be a starting point<p>Edit: Some initial ideas:<p>- Code can be deconstructed into blocks, and where the code is not self-documenting, prose can be added. Or even visualisations etc if a block is conceptually tricky to grok. You could even have MOOC-style validations to verify reader understanding for each block.<p>- Some kind of topology of the blocks should be generated based on how they interact and how they are conceptually related<p>- The author creates a few &#x27;starting points&#x27; for different audiences, e.g. &#x27;if you&#x27;ve used X before, start at Y&#x27;<p>- From there next blocks to read are auto-suggested to the user. A map or network diagram of all blocks is also provided so the reader can chart their progress and see where the &#x27;big ideas&#x27; lie.<p>Edit 2: This also really reminds me of Bret Victor&#x27;s &#x27;Humane Representation of Thought&#x27; lecture (<a href="https:&#x2F;&#x2F;vimeo.com&#x2F;115154289" rel="nofollow">https:&#x2F;&#x2F;vimeo.com&#x2F;115154289</a>, 45:40) where he says there is a conflict between code being an engineering specification and an authored work meant to be read by humans.