Search results

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.

I think traditional help authoring tools (HATs) will fade in place of more collaborative tools like wikis
I think traditional help authoring tools (HATs) will fade in place of more collaborative tools like wikis

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).

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.