How writing in the cloud has improved the Orbeon Forms documentation

We have recently finished moving all our documentation to the Orbeon wiki, powered by Google Sites.

All the way back to 2003 (maybe 2002) the documentation of the Orbeon platform was written in a text editor with an XML syntax. Nicely structured markup has benefits, such as the ability to process files through XSLT and XML pipelines and to shift formats. But in reality we didn't make much use these capabilities.

On the other hand, we found that writing new documentation was tedious with that system. Worse, quickly amending documentation was a chore: you had to locate the XML in your code, type funny markup you had to constantly lookup, make sure a servlet container was started so you could see the result; then commit the result to version control, and check it out on the other side to make it available online.

In 2009, we started using Google Sites and writing all our new documentation there. What we have found is that the turnaround time is much faster this way (even as frustrating as Google Sites can be at times). You find a typo or a paragraph that sounds a bit out of date? It's fixed in a matter of seconds. You need to document this new feature? You are up and running immediately. That's the same process that allows Wikipedia to evolve so fast (Orbeon being a bit smaller than Wikipedia ;).

So all in all we are very happy to have made that decision.