November 26, 2005

Open Source Project Wiki

Lately, the wiki has become the must-have tool for any open source project. Some use it for a home page others use it for project ideas and organization, or just community documentation, no matter how its used, it has become a necessity for every open source project. However, I think its important to recognize that even though wiki's have moved to the central location for project information, they are by no means the source of all the projects information. While project documentation and FAQ's have steadily moved onto to the wiki, bug information, component (and project) status, and certain coding information has not been moved over.

First off, there are obvious questions of why any information should not be moved to a wiki. Wiki's generally lock you into a data store (such as a MySQL) where more traditional text file documentation allows it to be moved in between storages, easily. Also, wiki's are documented by a person free-form (for the most part) allowing for inconsistencies in formating (such as different heading sizes or styles, or a table on the right or left side of the page). Form input project aids, such as bugzilla, limit the formating problems as they greatly limit the amount of data the user can input and format the data for the user.
Despite these issues wiki's are the fastest growing project aid around. By using a wiki, many barriers are broken down between a projects core developers and those new to the project. Anyone can in fact edit a wiki and offer their support to the project. This simple editing style, greatly reduces the barrier to updating a projects information. Wiki's also bring the benefit of bringing lots of spread out information into a single place. Documentation that was traditionally done in code and then brought to the web with the likes of doxygen are constrained in their editing capabilities.

I'll confess, at this time, that the reason I started thinking about this topic is because of something the Hula Project gets asked all the time. Whether it be on mailing lists, irc or even in person-to-person communication everyone wants to know what the status is. Some want to know the status of the entire project, others just a certain feature or even just of a bug. While some of this information might be available (what is the status of remaining bugs dealing with an OSX port?) others might be more complicated to define (is the AJAX interface usable yet?). Whatever the question, status is definitely of interest to the open source community, and it is important that projects outline their status on the website.

I think these status questions can better be answered through a powerful wiki built specifically to support such projects than it is done now. To correctly build a site that answers all of these questions, the site would have to break projects down into a set of components. Naturally, open source projects are broken down this way to allow developers to work on different parts, so it makes sense to take advantage of this. Each component should be given a wiki page (obviously a simple component template would be beneficial here), in which the following information could be defined: Component name, authors, current maintainer, who is working on it and what are they working on, status to next release, list of bugs associated with component, and documentation of that component. What makes the wiki great, is the simple fact that the text on it is written by a person, for people. If a note needs to be made about a certain detail, it can be inserted, by even those with little programming experience. I have included a crude example of what this could look like here.

Some of the new components would be better created if they were created as extensions than hardcoded. The following extensions will be aimed for Media Wiki as that is what I'm familiar with. The Component Status bar would work well as an extension as it could be made to look very nice and not burden the component page programmer. For example: <ComponentStatus level="4" />.

The Bugzilla and CVS/SVN extensions would be a little more complicated. Because most wiki's cache the created page after editing, this information would have to be refreshed by the server every so often. Another option would be to have the wiki mirror the bugzilla or CVS/SVN XML and then us AJAX to pull down the information down live. This data could be organized nicely with DHTML allowing for a bugzilla table that shows just the first 5 bugs but gives the user the option for clicking for more, or even the ability to sort the table by any of the headings. For wiki syntax something like <Bugzilla component="AJAX Interface" NumToList="5" />.

Documentation can likewise be separated and updated on a wiki. It would be great if a doxygen like application was able to be run and export to wiki format. I haven't looked around but I have no doubt that this has been worked on by someone, somewhere.

In the end, what do I really want? Wiki Customization. Wiki's are very customizable out of the box, but what I've found is that they aren't perfect for every situation out of the box. One use of a wiki (one that a group of mine tried this semester) is as a means of group information sharing. When each person of a group needs to come up with a couple ideas, or just general brainstorming needs to happen between meetings, a wiki might make sense. However, wiki syntax can still seem archaic to some people, so why not have a 'add item to list' link at the bottom of each list. When you click on it, a textbox can show and you can add an item right to the list, e.g. Tada Lists.

Posted by gasiorek at November 26, 2005 06:54 PM | TrackBack

You might want to have a look at Trac. It's designed for integration with subversion and includes a wiki and an issue tracker. We use it at work for projects and like it a lot.

Posted by: Matthew Bassett at November 28, 2005 07:18 AM

sounds like a lot of paperwork. I hate paperwork.

Posted by: chuck at November 28, 2005 08:30 AM

Very interesting site, beautiful design, thank.

Posted by: Nelly at January 13, 2006 05:51 AM

Ă€ good site, good short contents of the good work. Ă‘ongratulations !

Posted by: Halo at January 16, 2006 01:25 AM

I love this site so so so much :) Cool site!!

Posted by: Dominic at January 16, 2006 01:26 AM

It's a very good site !! Very nice work, admin :) Good luck !

Posted by: Hero at January 16, 2006 03:14 AM

It's a very good site !! Very nice work, admin :) Good luck !

Posted by: Hero at January 16, 2006 03:19 AM