Dexy and Literate Documentation

See "Why The World Is Ready For Dexy" for the lead into this post. The short version: most tools for building documentation are substandard, and most attempts at "fixing documentation processes" are flawed. But there's this new project called "Dexy" that is doing something that is pretty exciting.

Basically, Dexy is a text filtering framework, you write documentation, code samples, and code, and then you tell Dexy how to stitch everything together, and bingo. It's success, or potential success, is built around its simplicity and flexibility.

This model Dexy proposes something called "Literate Documentation," which is a cool concept, which expands upon the notion of "literate programming," both concepts require a little bit of unpacking.

Literate programing is the idea that code, documentation, and all specifications should be contained in one file, with blocks of machine readable code and human readable text should be interleaved with each other. Literate programming tools, then take this "mega source" and build programs that do cool things. There are a number of literate programming tools, and some notable programs that are written in this manner, but it's not particularly popular: code and text tend to flow in different ways, and a manageable literate programming text, is often not particularly maintainable software.

Literate documentation, on the other hand, as implemented by Dexy is documentation where the documentation is compiled from an amalgamation of text and code which can be run and tested at build time. You write code snippets and documentation snippets, and a tool like Dexy takes all of it, runs the code and stitches together a document out of all the pieces. Then, anytime you need to make a change to the code, or the text, you rerun Dexy and the documentation mostly tests itself. Good deal.

I think it's not yet obvious if Literate Documentation will actually be a "thing." It's a great idea but, like literate programming, it's unclear of how this kind of practice will actually catch on, and how useful/feasible writing documentation will be in this manner. "Dexy the method" may or may not find greater acceptance, because "Literate Documentation" may depend on developers writing documentation. At the same time I think that "Dexy the tool," is certainly a valuable contribution to the field of technical writing. Nevertheless, I think there are some important things about the way Dexy works that are worth extrapolating.

(Links to `tychoish wiki <>`_ pages concerning `technical writing <>`_ in some state of existence.)

  • Atomic Documentation. Dexy reinforces the idea that documentation should be written in very small units that are self sufficient, and address very small and specific topics, questions, and features. The system which builds and displays documentation should then be able to either usefully present these "atomic" units or stitch more complete documentation together from these units. This makes documentation easier to maintain, and arguably makes documentation more valuable for users.
  • Compiled Documentation. The "end-product" Documentation should be statically compiled, unlike (most) web-based content that is dynamically generated. This allows writers and teams to verify the quality of the text prior to publication, and allows the "build system" to automate various quality control tests. Documentation is particularly suited to this kind of display generation because it changes very irregularly (no more than a few times a day, and often much much less often.)
  • Pipes and Filters. the process of publication can--like code--is basically passing text (and examples) through various levels of processing until the arriving at a "final product." Dexy is very explicit about this and provides writers/developers a framework to manage a complex filtering process in a sane manner.

I look forward to thinking about these aspects of documentation and documentation systems, and about how writing texts with Dexy, or in the "Literate Documentation," mode affects the writing process and the shape that texts take. I look forward to hearing your thoughts in the comments or on the wiki pages!

comments powered by Disqus