Ramping Up on Mediawiki

by Tom Johnson on Dec 6, 2009
categories: technical-writing • wikis

I mentioned in a previous post that I think traditional help authoring tools are becoming less and less viable for robust software projects in which multiple subject matter experts in distributed locations need to collaborate, and when these same subject matter experts need to own the documentation after release.

This wasn't just a fleeting thought. I spent the last couple of days last week getting buy-in from project leaders on wiki formats for all of my upcoming projects. I thought we might be using Confluence in addition to Mediawiki at my work, but because learning and maintaining two different wiki platforms is onerous for both engineers and content contributors, we decided to stick with just Mediawiki.

Surprisingly, when I explained the need to collaborate with multiple contributers, and also expressed for business departments to own the documentation after I created it, the senior leaders gave me immediate approval to use a wiki format.

So I've been ramping up on Mediawiki lately. In some respects Mediawiki is similar to WordPress, and in others it's not. For example, both WordPress and Mediawiki are open-source PHP web-based platforms with MySQL database backends. After creating a database and user, you set up the sites through an installer script and configure the display through CSS.

Both platforms have themes/skins that you can download and apply to your wiki. Both platforms have thousands of plugins/extensions that will extend the functionality of the software. Both platforms have vibrant online communities with thousands of users participating in forums, blogs, and other groups.

However, there are also some key differences between the two. The main difference is that Mediawiki has no user interface for managing the content, whereas WordPress does. With Mediawiki, you work a lot with a file called localsettings.php, which you have to FTP back and forth.

Additionally, with Mediawiki you sometimes search for the files you want to modify and then edit them within the browser interface. Mediawiki has a lot of namespaces, so creating a page with a certain prefix before a colon puts the page into a particular group and it gets treated differently.

I previously thought wikis were fairly primitive and limiting in terms of format. I'm now realizing that wikis -- at least Mediawiki -- is incredibly robust. There's a lot to learn. For example, to impose structure on a wiki, you can label pages with categories and subcategories. When you add [[Category:Oranges]] to a page, it puts the page in a category called Oranges. Then you can dynamically pull together all pages with this category label. And you can add subcategories by opening the subcategory page and adding the parent category tag.

"Category" is in a Mediawiki namespace, and there are dozens of these namespaces. Through the Category Extension tree, you can automatically show all pages within a category in a collapsible tree. The tree uses AJAX to collapse and expand. To install the extension, you add some code to your localsettings.php file and upload the extension files to your /extensions folder. You can also access a special page for browsing categories by searching for special:categorytree.

Templates are snippets of reusable code. For example, if you have a note style that you want to reuse again and again, you create a new page like this: [[Template:Note]], and add your style. Then when you want to use your template on a page, you just add {{Template:Note}} and the code appears. It's essentially a php-include.

I only add this detail here as an example of the underlying robustness of the software. Previously I thought wikis might be limiting because the formatting options seemed so primitive -- either bullets or numbers or headings, and not much else. Now I realize that I have so much to learn. I'm only on stair three of about a hundred stairs.

Over the next year I'll have my head deep in Mediawiki, so expect to hear more about it from me on this topic (and wikis in general).