October 26, 2006

Documentation for those of us that love code

So as I’ve mentioned before, my day job involves a rather large web content management system by these guys, and it runs on a fairly common (for enterprise-level stuff) hybrid of native code, J2EE, XML and Perl. Add to that the resources that make the website itself shiny like stylesheets and javascripts, and there’s no possible way you could come up with a consistent method of documenting all that code, right? Right?

Wrong. One of my colleagues (Hi Alex!) passed this link around earlier in the week:

Natural Docs is (as they put it) “an open-source, extensible, multi-language documentation generator. You document your code in a natural syntax that reads like plain English. Natural Docs then scans your code and builds high-quality HTML documentation from it.”

Boom. Right there. If it supported Objective C, I would be utterly, totally sold on using this in everything I do.

See, the fact is, I suck at documentation. Sure, I can spell. I have pretty decent grammar (most of the time). Generally I don’t misplace my punctuation (Hello everyone younger than me, I’m looking at you!). And when push comes to shove, my documentation doesn’t suck when I actually write it - but actually sitting down and spending time writing it in the first place? Puhleeease (Yes, I can see all you corporate IT managers shaking your heads up the back there. Deal with it, programmers like to program, not cover your arses). By the way, I’m talking about serious post-code documentation here - anyone who’s ever worked on anything larger than “Hello, world!” will tell you how important specifications are to the success of any software project - I don’t believe Natural Docs have quite perfected the whole “suck the idea out of you and your client’s heads and document it for you” module just yet.

I may just have to look into what’s involved in adding Objective C support to Natural Docs, because this could be the beginning of a beautiful friendship!