A Wiki as the Source?!?
By mcraig on Sep 05, 2007
One of the reasons I came to Sun was to do structured documentation. Jon Bosak was working at Sun when he "fathered" XML. How could one get any closer to the center?
When I finally got a chance to go out for something to eat with Jon Bosak, he seemed more interested in General Robert's Rules of Order and electronic democracy.
Structured documentation is fantastic when you want to process and publish the content through different systems in different ways. With Directory Server Enterprise Edition, we run a cron job nightly that builds our docs checked out from the source tree, looks for issues in the production process, checks that all the links point somewhere valid, and posts the very latest on our internal site every morning. We can generate PDF, HTML, JavaHelp, now even WikiText. We are way ahead of what we used to do years ago, painstaking generating everything by hand.
With the OpenDS Wiki, we had a completely new set of docs to write. We decided therefore to take the plunge, sacrificing the use of our great structured doc tools to the larger goals of lowering the bar to authors, and of dropping publication lag from overnight to instantaneous. Even better, since OpenDS development is out in the open, the Wiki is constantly crawled by your favorite search engine (as are the mailing lists). You no longer have to be in the know to get access to the latest content.
To what extent do the benefits of traditional documentation outweigh the benefits of having documentation on a Wiki? Feel free to answer in the comments for this entry.