Dokumenting with DokuWiki

Jun 26th, 2009

At my current summer co-op, I’ve been tasked with setting up a wiki on the company intranet to make a variety of internal documentation more accessible, editable, and revision-trackable. As far as wikis go, MediaWiki tends to be the default choice; it’s reliable, extensible, and has vastly greater mindshare than any other wiki platform thanks to the omnipresent hive-mind of infallible factoids[citation needed] that is Wikipedia.

Figuring that MediaWiki was probably overkill for this project, I struck out in search of something that would be easier to install and configure for me, and easier for non-technical users to maintain. What I found was DokuWiki, a somewhat minimalistic wiki platform that explicitly aims to fulfill the documentation needs of “developer teams, workgroups, and small companies.” Perfect!

As I soon discovered, one of DokuWiki’s distinguishing features is that it does not make use of a database for storage, as so many other wikis and content management systems do. This makes installation incredibly simple right off the bat: Just drop the files in a directory on your web server and go. All of your pages are stored as plain text files (e.g. another_wiki_page.txt)  in a directory hierarchy that matches the hierarchy of “namespaces” you create on the wiki. In this way, your content remains organized and perfectly readable even when you take the wiki software out of the equation.

For the most part, DokuWiki’s syntax is pleasant and sensical. Instead of MediaWiki’s odd multiple-single-quotes scheme, you have //slashes// for emphasis and **asterisks** for strong emphasis, which feels more intuitive. Instead of MediaWiki’s bizarre syntax differences between internal and external links, DokuWiki treats them all the same: [[link_target|Link Text]]. But then again, there are some strange and arbitrary syntax decisions on DokuWiki’s side, like the fact that the largest headings are surrounded by ======Six Equals Signs======, and the number of equals signs goes down by one for each sub-heading level. Weird, though I suppose it’s in the name of plain-text readability.

Uploading images and other files to DokuWiki is a breeze, thanks to a pop-up media manager that includes a multi-file Flash uploader and can insert wiki-links to your files with a click. Nifty media icons abound in DokuWiki’s output, with PDF files, Word documents, and more each getting their own instantly-recognizable icons. External links and email addresses also get unique icons, making them stand out nicely on the page. The “pretty by default” approach extends to text, which gets automatic curly quotes and various other typographic entities in much the same way that WordPress output does.

Given that I’m using DokuWiki for documentation on a company intranet, I would be remiss if I didn’t mention what an absolute cakewalk it is to integrate your own authentication scheme into it. If you already have a table of users in a database somewhere, as I did, you can set up DokuWiki to authenticate against it in the time it takes you to write a couple of SQL queries. There are other built-in authentication modules you can use, and if none of them meet your needs, writing your own is surprisingly easy (and well-documented) if you have a decent knowledge of PHP. There is also a fairly comprehensive ACL system that becomes much more useful if you set up your authentication scheme to provide “groups” to DokuWiki, or if you’re using the built-in mechanism.

One downside I’ve encountered in terms of usability is DokuWiki’s strict adherence to a particular naming convention for both page names and media file names: Only lowercase letters, periods, dashes, and underscores are permitted. The aesthetics of this decision leave something to be desired, especially since the name of the page you’re on is (at least in the default theme) displayed at the top in very large text, and probably:looks:ugly_as_sin. I’m not sure why capital letters and spaces are disallowed, since they are both quite safe to put in a filename. You can set an option to superficially replace the ugly page names with the contents of the first heading on the page in question, but this just makes the page’s “real name” harder to discover when you have to link to it, and the visual duplication of the page title and the first heading is far from nice-looking.

Thankfully, DokuWiki presents itself very well in all other aspects, and the overall package has so many good things going for it that I can’t help but give it my recommendation. If you want a lightweight, documentation-oriented wiki that feels almost as slick as WordPress but gives off a more techy vibe, DokuWiki can definitely take you there.

Fresh Styles and WordPress 2.8

Jun 19th, 2009

About a week ago I whacked the auto-upgrade button on my admin interface to take me up to WordPress 2.8. It is really nice how you can upgrade even the core system in a single click, right in the browser, without fiddling around on the server.

Unfortunately, after the upgrade, every other form submission on the backend was giving me blank pages and error messages, and I determined that my outdated theme was likely to blame. What’s more, I had foolishly made several customizations to the theme’s CSS, which of course would not be preserved when I upgraded it. Since I always thought that theme was a bit dull, anyway, I figured it would be as good a time as any to search around for a new one. As a side note, the new theme browser/installer in 2.8 made this task incredibly easier than it had been before.

So now we’re rolling along error-free with a new theme and all my customizations safely stashed in the Custom User CSS plugin. I’m still not totally satisfied with this theme (especially the weird fadey drop-down menus) and will probably change it again in the future, but that’s life. On the positive side, the main content area is now just wide enough to squeak a 640-pixel-wide image into.

One of the non-CSS customizations I had made to my old theme was to add several lines of PHP that would prevent my content from being “texturized” – straight quotes replaced with smart quotes, doubled hyphens replaced with real dashes, etc. When I enabled the new theme and the texturization returned, I was surprised to notice that the one thing about it that really annoyed me had apparently been fixed: Straight quotes inside <code> blocks are no longer converted into smart quotes. I’m not sure if this is a fix on the part of the theme or WordPress 2.8 (I don’t see anything in the changelog about it), but either way I’m happy enough to leave the feature turned on.

The one thing that really impressed me about 2.8 is the new syntax-highlighting, line-numbering, generally awesome-looking code editor. This is the first time I’ve seen anything like this, though in retrospect it seems like an obvious idea: If we can already do WYSIWYG editing for normal content, why not apply some nice formatting and colors to code-editing as well? If you’re curious to see what this looks like, the WordPress 2.8 release announcement has a slick video overview that touches on the code editor and various other new features (I recommend watching it, if only to witness the incredibly high production values for it being an announcement of a point release).

C64 Twitter Madness

Jun 18th, 2009

My roommate recently alerted me to the handiwork of the lyrically-named Johan Van den Brande, who apparently has far more free time and Commodore 64 know-how on his hands than myself. His Twitter system, called BREADBOX64, is coded in C and takes advantage of an Ethernet add-on cartridge to allow a completely stand-alone system, unlike Twittjr. And the really impressive part is that it runs on just 64KB of RAM and a 985KHz CPU (yes, it’s so slow we have to use Kilohertz)!

Since the oldest computer I had growing up was a Windows 3.1 pizza box, the only ancient hardware I know how to run is IBM-compatible DOS machines, and I’m always fascinated by people doing crazy things with C64s or Apple IIs or Amigas. I especially envy the C64 for the amazing “retro-hacker” community it has built up, and it’s really nifty that someone thought of putting Twitter on one, just as I did with the lesser-known PCjr.

Eversion

Jun 12th, 2009

I have just discovered what is quite possibly the most utterly terrifying videogame in existence. It is called Eversion, and it definitely should not be played alone in the middle of the night in a completely silent house (hint: I did this and immediately regretted it). Here is a screenshot:

p-eversion-screenshot

What’s that? You don’t believe me? Well, it’s your funeral. Just make sure all the lights in your house are turned on before playing. Hell, go for all the lights on your street. It can’t hurt.

Where are we going, TomTom?

Jun 12th, 2009

Despite having attended RIT for two years now, this summer is the first time I’ve had a car in Rochester, and I figured I should have at least a vague idea of where I was going before I put foot to accelerator. Since dead-tree maps are for old people, and I like finding electronic solutions to my problems, I ended up buying a TomTom ONE 130•S, which is about as entry-level as you can get in terms of GPS devices.

I’ve found it to be quite a useful little gadget, and incredibly easy to use at that. It may be an entry-level model, but it doesn’t feel like the features have been deliberately crippled to make you want to upgrade. If you just need to get from point A to point B, the 130 will get the job done with minimal hassle. Mine is the “S” version, which means it can speak the names of streets and highways; the pronounciation is invariably mangled, but it still confers the advantage of knowing what street signs to look for without taking your eyes off the road.

p-tomtom-car

One oddity I noticed was that the speech synthesis frequently says “semicolon” in the middle of highway names. I’m guessing that the underlying map data expects the synthesizer to pause for a beat when it sees a semicolon, instead of saying “semicolon” aloud, but such is not the case. It might also be something weird in the data for Rochester, since I’ve only noticed it here.

Speech glitches aside, the only bad thing I can really say about this TomTom is more about the software that comes with it: It seems very intent on always being loaded in the background, setting itself to run at startup and minimizing to a tray icon when you hit the Close button instead of actually closing. The option to disable the former behavior is unintuitive, and the latter can’t be disabled at all. It seems like a well-made piece of software otherwise, though, so I’m willing to give TomTom the benefit of the doubt, and the device itself has yet to disappoint me in any way.

Interestingly, after being guided along the same route to and from work for a few weeks, I’ve unconsciously memorized the turns to the point where I don’t need the GPS anymore, though I still couldn’t tell you what roads I’m driving on. Excellent procedural memory, terrible semantic memory. Whee!