Improving Wiki

I've already gone over my desire to add more tools and procedures to our distributed team development process. My next issue is with one of the tools that I like quite a bit. I think that the way we're using Wiki is leaving something to be desired.

Get Organized

The first problem I have is that it's horribly disorganized. It's extremely hard to find things. Design docs, developer environment setup, refactoring plans, third party tool evaluations, etc are all jumbled together. You can't navigate from the top level page to anything useful. That's not a huge deal for me since I'm more about searching than the dreaded hierarchy, but the search also leaves something to be desired.

Someone at my company suggested that the problem stems from the fact that it really takes someone with an overarching idea of (and a strong passion for) how to organize things. I don't think it needs to be that strong, but some simple high level guidelines of what goes where would help. It's great that anyone can add or edit a page, but in the absence of any guidelines our Wiki is looking more like a wall with 300 Post-It notes on it than anything really useful.

When Was This Updated?

The next problem is that Wiki pages usually don't get updated when things change. This leaves the Wiki full of a bad combination of mostly accurate and completely incorrect information. The Wiki page on the design of a module or its example code is too far away from the code.

That's why I like Javadocs so much. The documentation is right next to what you're documenting. If we think that not everything is best to document in the code, I'm thinking we may want to at least put a link to the Wiki documents in the Javadocs and make the evaluation of a Wiki update a part of the peer code review check-in process.

You're Not Revision Control

All of the design docs, tips, example code, support notes, and pretty much everything else related to the code or the product are accurate for a particular version of the system. If you're being good about updating things then the pages in the Wiki reflect the way things are more than the way things were.

For multiple versions of software, it's easy to forget how things used to work. Yes, there's some crappy versioning built into most Wikis but it's not really what they do best and it shows (just like their integrated search). Tying a Wiki page to a release of your software requires putting an artificial mechanism in place (like a naming convention, a structure to the hierarchy, or tagging if the Wiki supports it) or finding a Wiki that provides more powerful tools for finding topics by version (repository style tagging and viewing of a Wiki).

Integrate This *Flash*

Probably the easiest solution would be to choose a Wiki tool that supports top level categorization of your Wiki into sub-Wikis (like what Twiki does with webs). One downside would probably be that you would start off each new release cycle of the product by copying the previous category over to the new one, but maybe that's not that bad. You'd probably also want to at least do some of the high level guidelines and have the topic / category structure closely mimic your code where appropriate.

Another idea I was thinking of involves looking into either a file-based Wiki that I can directly put into the revision control system of my choice (Subversion, baby) or that directly integrates with RCS of my choice (did I mention Subversion?). At least for code related documentation (design docs, examples, dev environment setup, etc) this seems to be an intriguing solution. If the topic relates directly to a package / module then its path should directly mirror that. Otherwise it goes under one of several high level categories like I mentioned parenthetically. Reviewing the Wiki documentation would be part of a peer code review regardless of how the versioning issue is solved.

These release specific Wikis would still be published by the build to some internal website so that a super-Wiki could be created for support, QA, etc. I'd also think about maintaining the non-RCS Wiki for any information that doesn't relate to either the product or a specific version of the product (whatever they may be).

I'm still debating which approach I like best, but I am definitely certain that I think what we're doing now is inadequate.


Leave a Reply