Have stumbled across this post on LtU today.
You know, I am writing this post using Markdown, a nice markup language created for the purposes of formatting plain-text writings. Using Markdown, I can create hyperlinks, lists, insert images etc. HTML can be use to achieve the same purpose, but Markdown is better for several reasons:
Usually, we draw a solid line between programming languages and markup languages. However, markup is usually present in the code written in the programming language as well. Consider the symbol documentation, or comments. Not surprisingly, I do not use Markdown for that purposes. Reason? Markdown knows nothing about my code. I can not insert a meaningful link to a symbol, for instance, and hope for some tool to update the dependencies when I decide to rename that symbol later. On the other hand, Javadoc and what-do-you-call-it documentation system from MSFT both do that.
How about other documentation? I believe that keeping the docs alongside with the code is a good practice. Expose it over the web and you can use your wiki a lot less frequently. However, there are issues with that. Suppose I am creating an architecture definition document. I’d love to link from the doc to the module in the source tree. Markdown can not help me here, and markup languages akin to Javadoc do not really do a good job when you try to use it for standalone documentation. Moreover, none of the above is very extensible, so if I want to embed a umlgraph diagram into my doc… well, you better shoot me in the head right now.
So how Scribble handles that? Well, a document written in Scribble is essentially a module in your system, and it behaves as such. If you try to mention some symbol in your doc, it has to be imported from the relevant module — otherwise, you’ll get an error. You can import and use any functions you want, from your modules or from third-party libraries. (Guess you can do the reverse trick and link to documentation chapter from the module, too.) Scribble can be used as a stand-alone tool or in-place, in form of a symbol documentation or code comments.
When you compile the Scribble document, it essentially runs the program it denotes and provides you with the output. If you ever worked with TeX, you know the drill.
Where this approach can be useful besides creating system documentation? One other use case that immediately comes to my mind is test execution. One can create a set of test cases in Scribble, and the output will be a formatted execution report, always up-to-date.
So why won’t we take it and use on a daily basis? Well, I guess you could, if your project is written in PLT Scheme. I see no particular reason, however, why this approach can not be adapted to other languages. The easiest thing to do, I guess, would be to adapt it for Clojure. Its native metadata handling make the problem especially interesting.
If you are interested, I strongly suggest to read the original paper, it’s only a dozen pages long.
