Paul Hammant's Blog: Project Documentation Thoughts

Are you allergic to project documentation?

Documentation is a hard thing to convince any team to do, whether you pay them or not. Over the years Open Source in particular has been scarred by poorly documented projects. In 2000, Java projects were using XDocs/Stylebook/DocBook (if you take Apache as a barometer). A few years later we were using wikis, and Codehaus settled on Confluence . A few years ago, some feel that that wikis in general and Confluence in particular are part of the problem. Its difficult to out your finger on why. Wiki’s can certainly allow pages to degenerate into conversations with variable levels of eloquence or authority. Enterprise wiki’s like Confluence can feel unwieldy in day to day use - though Atlassian increase your options all the time.

Many of the project I am involved with use XSite for their documentation. XSite is a blend of XStream and Sitemesh allowing you to edit pages offline, and run a build to make a static site. That’s a barrier to use itself of course, but I’m willing to pay the price. I get to use DreamWeaver, SeaMonkey or NVU as a WYSIWG editor on real HTML and the template for the site. I don’t feel locked into to some obscure page language, or database schema - this is plain HTML for me held in Svn.

At OpenQA for the Selenium project(s) we use Sitemesh directly. The same tools, and WYSIWYG lingua-franca but when I do a commit, there’s a build box that picks up the change and deploys it. Sitemesh is more costly on the server side than static HTML, but the price is often worth paying as there’s no build stage for people making changes.

Of course the downside of Sitemesh based solutions is there is no “live” editing solution, but hopefully I’ll pick up Cozmos (site down presently) again soon, or someone from the Ruby community will deliver all of the same idea in one-tenth of the lines of code. GoogleCode’s wiki is close, but not close enough for me.