A Wiki as the Source?!?

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.

Download OpenDS

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.

There are at least two problems with this approach, however. One problem lies with a characteristic of structured documentation itself. It takes some expertise to write structured documentation. Not much expertise, but enough to prevent people from getting involved casually. Another problem comes from the speed of early release. Even in the middle of the night, tomorrow morning is a lot later than right now.

<script language="javascript" src="http://www.polldaddy.com/p/99413.js"> </script>

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.

Comments:

This is interesting.

Ever since we launched http://wikis.sun.com I see more and more docs being migrated to the wiki format. A bunch of folks at Sun are actually working on migrating their legacy SGML docs into our wiki format.

It definitely appears that giving up the benefits of structured documentation in favor of community participation is the trend these days.

Posted by Igor Minar on September 08, 2007 at 01:44 AM CEST #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Mark Craig writes about Directory Services products and technologies. The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today