LiteratePrograms.org: An Executable Wiki

Knuth's literate programming is an excellent idea.

The literate programming examples I have seen lack suitable modern integrated development environments. The idea of interweaving source code and commentary in a book style has few advantages over Javadocs, Doxygen, and the like. And they are more work for the developer.

The concept of coupling comments to code is a good one. What we need to do is loosely source code to its comments using an intelligent editor. Mute the music and watch the end of the following video:

http://www.youtube.com/watch?v=u3QqjhzhnAw&t=1m41s

Essentially, a dual panel editor. On one side is source code, on the other are the comments linked to each line in the source code. You could still generate the wiki-like interwoven documentation, but you could also generate the documentation as a single document (without source code).

Further, since the documentation editor is independent of the source code editor, the documentation could be written using a simple mark-up. You could also embed business requirements within the commentary to suggest the exact business requirement being met by the code (using linked text and a single source; update the business requirement and you know what code needs to change). Conversely, formal technical documentation (user guides, administration manuals) could link directly to the source code commentary (a single source, once again).

I'd be interested in reading the disadvantages to such a dual editor system.

The best example I can think for online, executable wikis is http://scraperwiki.com - it allows you to create web scrapers, then periodically runs the scrapers and offers up the data in a nicer feed. As it's a wiki, anyone can reuse the scraper, or fix it when the structure of the page changes and the scraper breaks.

But it doesn't follow the example of literate programming, I guess largely because the code is generally boring, and written to quickly solve a problem, not primarily to act as an exemplar.

I've been trying to do Literate Programming in one project and somehow I can't stop feeling like this is a big time sink (writing down all this prose) that ultimately makes programs harder to understand (single code module can be spread across half of the file) and harder to modify (when you change one part, you have to look through half of your prose to check if there is something to be removed/rephrased).

I don't know, maybe I'm doing it wrong?

"a unique wiki where every article is simultaneously a document and a piece of code" <- except that article

I wrote this site to combine Markdown documents and executable <script> sections.

http://wiki.pageforest.com