OSSBarCamp Talk on Automated Documentation

You can download PDFs of the handout from my talk at the September 2009 OSSBarCamp in the sidebar. Unfortunately the hyperlinks aren’t live in the PDFs, so here are the software projects I mentioned in my talk. The outline was done using FreeMind which I’ve just started playing around with.

Webby

Webby is primarily a tool for building static websites, but its combination of Rake and a generic filter/helper structure makes it phenominally powerful for managing any kind of collection of documents. I use Webby as the glue for my Automated Documentation “stack”.

Gorgyrella

Gorgyrella is my Ruby port of the Python library Idiopidae. Gorgyrella lets you add special comments to your source code to define sections, which you can then pull out to include in documenation or to execute with Dobby.

Dobby

Dobby is still in its infancy, but its goal is to allow you to run snippets of code in an interpreter and display the output in a document. What makes it especially convenient for writing tutorials is that you can keep a Dobby session open, run a setup script invisibly, and only show the output of running a few lines of script at a time but with the memory of any previous commands still intact. Dobby currently supports R and Python, but in principle can be adapted to support any software with a command line interface.

For syntax highlighting, I prefer Pygments but Gorgyrella also has support for UltraViolet and CodeRay. It is very easy to add support for other syntax highlighting packages.

The projects which use Webby+Gorgyrella for their documentation are:

Surpass

Write native Excel files using just pure Ruby. This one has the screenshot automation.

RBloomberg

Interface between R + Bloomberg financial data.

Specifically for Arrrrrrrrrr users1, the rcom server allows integration with R and various Windows packages which can be scripted using COM/OLE. In particular, R2PPT integrates R with PowerPoint.

I currently use Bazaar for version control. It’s a distributed version control system and very easy to install and get started with. Once you have it installed if you want to check out the source code for Surpass to see how the documentation is compiled, then you just need to type:


bzr branch http://ananelson.com/code/surpass

and this will give you a bzr repo named “surpass” in whatever directory you typed the command. I’ll try to set something up with zipped copies of the latest version for those who don’t want to install Bazaar. Hey! I can automate that with Webby! ;-)

1 Laura picked a great day for OSSBarCamp.




Rafal Mierzwiak 29 Sep 2009

Hi Ana,

Just to let you know that you're talk was absolute 1st class, it was very professional and entertaining at the same time. I enjoyed every one bit of it, thank you very much for that!

I like the parallel you used, the one that went like 'when it comes to documentation we're now in a stage of where our testing was good few years ago', and that 'you're looking forward to improve it'.

I'm with you when you're saying that documentation maintenance is a time consuming task (to write it is another story, obviously, but in my honest opinion maintenance stands for the main issue here), and I agree we do need to work out some smart way to change the way we document projects, systems, applications.

Therefore I like a lot what you're trying to accomplish, it seems like you've got a vision so to speak.

Best of luck with your pursuit!