The origins of DWiki and its drifting purpose

February 24, 2014

One of the interesting things about writing Wandering Thoughts has been getting a vivid and personal experience with what happens when some code you've written gets repurposed for something rather different than what it was originally designed for. Because, you see, DWiki (the wiki engine behind the blog) was not originally intended to be a blog engine and what it was originally designed for shaped it in a number of ways that still show today.

(I alluded to this when I talked about about why comments aren't immediately visible on entries.)

Put simply, I originally designed DWiki as yet another attempt to build a local sysadmin documentation wiki that my co-workers would use. We hadn't shown much enthusiasm for writing HTML pages and I didn't think I could get my co-workers to edit things through the web, but I figured I at least had a shot if I gave them simple and minimal markup that they could edit by going 'cd /some/directory; vi file'. This idea never went anywhere but once I had the core wiki engine I added enough extra features to make it able to create a blog, and then I decided I might as well use the features and write one.

(From the right perspective a blog is just a paged time-based view over a directory hierarchy. So are Atom syndication feeds.)

One feature that this original purpose strongly affected is how comments are displayed. To put it one way, if you're creating a sysadmin documentation wiki, input from outsiders is not a primary source of content. It's a potential source of feedback to us, but it's definitely not on par to the (theoretical) stuff we were going to be writing. So I decided that (by default) comments would get a secondary position; if you were just browsing the wiki, you'd have to go out of your way to see the comments. As a wiki, if people left comments with seriously worthwhile feedback we'd fold that feedback into the main page.

(Adding comments was also a sop to the view that all true wikis are web-editable by outsiders. I wasn't going to make the wiki itself web-editable, but this way I could say that we were wiki-like in that we were still allowing outsiders to have a voice.)

Another thing that this original purpose strongly affected was DWiki's choice of text formatting characters, especially its choice of _ as the 'typewriter text' formatting character. If you're writing about sysadmin things it's quite common to want to set text in typewriter text to denote (Unix) commands so you want a nice convenient character sequence for it; _ looks like a great choice because almost nothing you write about is going to have actual underscores (they're very uncommon in Unix command lines). When I instead started using DWiki to write more and more about code, this turned into a terrible decision since _ is an extremely common character in identifiers.

(Another choice that looked sensible for writing about Unix commands but turned out to be bad for writing about code is using ((...)) for a block of typewriter text with no further formatting. The problem is that when you're writing about code you often wind up wanting to write about things with (...) on the end and that confuses the text parser.)

PS: In hindsight I can see all sorts of problems with my idea of a sysadmin documentation wiki. Even if I'd tried to market it better to my co-workers I suspect that it wouldn't have worked, especially as something that was publicly visible.


Comments on this page:

By Chris at 2014-03-26 14:31:24:

Can you elaborate on your postscript? My department has been investing a significant amount of resources into putting sysadmin documentation into a wiki. I've seen pros and cons with the approach, and am quite interested in your thoughts.

Written on 24 February 2014.
« The problem with indentation in programming languages
Nerving myself up to running experimental setups in production »

Page tools: View Source, View Normal, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Feb 24 01:31:00 2014
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.