Thursday, September 11, 2008

Kwiki - A Lightweight Wiki and Document Replacement Tool

Today, I was faced with that age old problem: how do I take an idea for a web app that I have some rough notes and a vision in my head and present it to a client? I've tried a variety of approaches, from Google Docs to hand drawn diagrams and still have yet to find the perfect solution.

Today, I revisited an approach I've used in the past: don't write up a document, but create a wiki that specifies the app. This seems like a good idea, because wikis are:

  • Fast and easy to edit - I won't get stuck trying to draw some impossibly complex diagram
  • Collaborative and typically have version control - no worrying about who has the most recent version of the spec
  • Allow you to support different pages, which should in theory model a web app

One reason I haven't used this approach in the past is that setting up a private wiki, isn't always the most hassle free activity. I end up spending all my time setting up the framework (and getting it work with Apache, MySQL, etc.), and none of the time working on the document.

Discovering Kwiki

Today, while browsing the big list of wiki software options I discovered Kwiki. What caught my attention was that Kwiki was described as being a simple wiki that didn't require database support.

Turns out, if you have shell access on a Unix system, Kwiki couldn't be easier to install and get running:

> svn checkout /usr/local/kwiki
> export PATH=/usr/local/kwiki/bin:$PATH
> kwiki -new /path/to/cgi/kwiki-01

It even comes with it's own built in web server, if you want to skip setting up Apache:

 kwiki -start 8080

And you're done...the wiki is running.

If I want to setup another Wiki (for another client's document) I just have to run:

 kwiki -new /path/to/cgi/kwiki-02

And it all just works.

Kwiki out of the box is really basic - and by enabling a couple of plugins, I got a fairly nice look & feel as well as version control support. Just what I needed to write up this document.

Next Steps

I've now written up and sent off the wiki to the customer, so I'm waiting to find out if they think it's a helpful way to understand the site. If they like the approach, I'm tempted to look into creating my own plugin for Kwiki. I'd like to add some basic wiki syntax that would add buttons, input boxes, check boxes, etc. to a wiki page.

With that plugin in place, I should be able to produce quick mockups that edit as easily as a wiki, but are still expressive as to what's going on in the app. But, I don't want to get ahead of myself.

The last thing I want to do is to develop a tool that I won't be using in the future.


  1. You should really take a look at TiddlyWiki. It's written in client-side JavaScript. I have my "home page" set up to a TiddlyWiki set up as a day planner. And I do as you describe -- a separate wiki/notebook for each project. Unless you have attached images you can email the wiki to someone as a single file and at least read the file (not necessarily write to it) in most mail readers.

  2. David Atter10:34 AM

    Hi, I use LionWiki ( for this purpose. It does not need database, requires only PHP >= 4.3 and webserver but is IMHO even simpler when it comes to use and installation. In its basic form, it's just one 35KB file but can be extended with plugins like comments or RSS.

  3. Thanks for the tip David - I'll have to check it out.