Actually, I have been doing this for some stuff now. I wrote my copy of tangle (based on noweb's notangle). I'm starting to write markdown files to that a liter

Actually, I have been doing this for some stuff now. I wrote my copy of tangle (based on noweb's notangle). I'm starting to write markdown files to that a literate programs for Dockerfile images (as well as the support scripts used in the docker images and support scripts to build/test/etc.). Since all of this work is in a git repo, it is nice to pass around documents so folks understand the thinking behind things. Also, (and the main reason I went towards it) is that when I pull what I need from the markdown files, I have steps built around to lint, test, and do additional checks to ensure the required naming, labeling, etc. It has worked well and reduced many `silly' errors when other folks use the images. Is it for everybody? Nope. But it works here. I also did LP many years ago when I worked at a place that produces custom software for embedded systems. Providing them with a friggin' novel about the program was also fun. But, we never .. once .. were told we needed to provide more documentation. LP has good points, but it isn't a one-size-fits-all. When asked to send some coding samples, it is fun to have a PDF file that starts 'Chapter 3: And Now, Security! Encryption and Other Pain Points!'