Even a chimp can write code

Monday, April 26, 2004

In search of a project documentation framework

I am evaluating a few project documentation frameworks to find the one right solution that will make the rest of this Release period more productive. There are a lot of user guides, tutorials and other documentation to be written and a powerful, user-friendly framework is essential before we move forward.

My research -- rather brief -- has led me to some good candidates: Forrest, Toot-o-matic and Maven. Each of these has it's own niche. So a straight comparison has no merit. Maven is richer and more appropriate from the project management perspective while Toot-o-matic churns out tutorials [a la developerWorks] rather well. Of these Forrest has impressed me the most. [Ladies and Gentlemen, it really is all that and a bag of chips!] Not because of what it can do, but because of what it takes to make it do what it can do.

Technical Writers are very rarely that -- technical. Forrest's simple site configuration and page content DTD make it quite handy indeed. It comes with a basic validation mechanism that can help trap newbie errors quickly. The rendering mechanism uses Cocoon and generates both HTML and PDF documentation. There is a lightweight server that will run your site, once rendered, so you can quickly check how it all falls into place. It took me all of a 1/2 hour to learn and implement a basic prototype [I translated an 8-page product release notes into its new avataar].

I will look at Maven and Toot-o-matic more closely in future posts.

Email this | Bookmark this