Show HN: Anansi – a NoWeb-inspired literate programming preprocessor
I came to similar conclusions as the author about the usefulness of literate programming. Even after &quot;taking it seriously&quot; and &quot;doing it right&quot; and all those other no-true-scotsman type objections. (see HATEOAS&#x2F;REST for more examples of these).<p>Initially, I was super excited about the idea. Imagine a world where you take a book off the shelf and peruse a master programmer&#x27;s in-depth explanation of the details of some famous software. What they were thinking, the abstractions they decided on, the algorithms they chose, the tradeoffs made. Wouldn&#x27;t that be an amazing world to live in?<p>In practice, very few pieces of software are written in a way that lends itself to a cohesive narrative. Software is written by numerous developers, layer by layer, often with hacks thrown in. New people come on, don&#x27;t understand the whole thing, change parts of it, and move on. The requirements change, and the system contorts itself to serve multiple purposes that weren&#x27;t envisioned by the original coders.<p>Keeping normal auto-generated documentation up to date under those circumstances is already a herculean task, literate programming asks more: maintain a story and flow and an overarching rationale. It&#x27;s just not possible for most software.<p>There is a type of software that lends itself to literate programming: the kind of software Donald Knuth writes. Written by a single author, with encyclopedic knowledge of the problem domain, excellent writing style (Knuth is very funny if you&#x27;ve read his work), and above all, the programs Knuth writes tend to be &quot;done&quot; at some point. There are bugs to be fixed, but no new features are added that might drastically change the narrative.<p>Most software isn&#x27;t like that, but if yours is, then literate programming can be fun.