literate programming is particularly well suited for shell scripts. Sh and bash scripts often have high documentation / loc needs, often involving external links, and they lack good composition primitives. literate programming fits it like a glove. I used this for a project (plug: "https://github.com/hraban/tomono", in org-mode w babel and noweb). it remains my favorite public snippet of code to this day.
One often overlooked cute aspect of lp is how a digression on code you tried, but chose not to incorporate, is first class with the same highlighting etc as active code. It isn’t relegated to a monochrome, non syntax highlighted and awkwardly indented block comment. I find this very appropriate, and it encourages documenting “tried but failed” experiments , which can be incredibly useful.
Edit: another really cool benefit of lp: the “examples” chapter = tests. You can tangle the examples into a test script and run them in CI. Very satisfying.
One often overlooked cute aspect of lp is how a digression on code you tried, but chose not to incorporate, is first class with the same highlighting etc as active code. It isn’t relegated to a monochrome, non syntax highlighted and awkwardly indented block comment. I find this very appropriate, and it encourages documenting “tried but failed” experiments , which can be incredibly useful.
Edit: another really cool benefit of lp: the “examples” chapter = tests. You can tangle the examples into a test script and run them in CI. Very satisfying.