Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

Search results

Ramping Up on Mediawiki

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

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

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.