For several months, I've been converting a few of my dotfiles into OrgMode files and using tangling to generate the config file and the same file generates HTML documentation. The point was to always publish them – and I finally have. See the HTML version or the github project. Note that the Org files are rendered in Github because Github is smart like that – it treats them the same way that it does with Markdown.
I stole, er, borrowed the system from Toon Claes. And, yes, I have had to edit a
Makefile to do this.
I found this documentation on my files to be more useful than I thought. Besides just the documentation of "why is this here" but it also helps in "why am I adding this?". Because the ultimate source is an Org file, I can do a better job documenting why I did something in the file then in the comments of the file. I can (and really should) link my config file to my OrgMode-powered knowledge base about what each thing does. That doesn't give the Internet reader much help, though. But is this documentation more for me for them? That I'm uncertain about.
I already repeated a lot of links from the Readme of this project. Hopefully these files are helpful to someone.