Using Mediawiki as a documentation tool

Some years ago, a coworker introduced me to using Mediawiki as a documentation tool and I got immediately hooked on it.

The biggest pro is that it’s very easy to use and install (millions of people already use it on Wikipedia) and you can use it for almost anything.
IT documentation is always changing and constantly needs to be updated, the harder it is to update – the less updated it will be, unfortunately.

I’ll start by listing some of the pro’s with using Mediawiki for your IT documentation:

  • Open source software, no cost for application, possible to install using L.A.M.P. or on a Microsoft platform using Screwturn Wiki.
  • One dedicated platform for documentation, you’re not forced to share environment (and search results) with e.g. other Sharpoint sites.
  • Fast and easy to create pages, update or rollback changes.
    Use standardized wikipedia code to create pages, or feel free to use the awesome WYSIWYG editing tool.
  • Built in version control for pages and LDAP / Microsoft Active Directory support. Restricted edit use for the IT department or give read permissions for everyone else.
  • Only text makes searches very useful and you always find what you are looking for. If you can’t find it someone probably haven’t documented it yet. No more having to download and open Word documents to find the correct documentation.
  • For offline use – Install a 3:rd party plugin for exporting to offline pdf-files.

The flexibility of using it for documentation however requires you to set some ground rules not unlike those used by Wikipedia.

Here are some rules I’ve found useful when implementing mediawiki:

  • One page per server, application or area of documentation. Never split it up in several pages.
  • Use descriptive page names and avoid names that can have multiple meanings.
  • Create templates (also stored in the wiki) for Servers and Applications that can be used when creating new pages.
  • Use headers to create a hierarchy for your page. Very useful when linking in to larger pages.
  • Use capital letters for Server names, makes them easier to identify.
  • Use the server & application pages for logging recent changes. Type in what you did and when you did it to make troubleshooting easier.
  • Force users to search before they create a page, to avoid duplicates with similar names.
  • Only allow upload of images (like screenshots or graphs) to the wiki. Never allow pdf, word or excel files to be uploaded. The wiki should not be a document store.
  • Assign one or more mediawiki evangelists who help out with the initial design of the wiki, they can also help out with questions from other users.

Software requirements for installing could be Ubuntu (or your favorite Linux distribution), MySQL, Apache and Mediawiki.

Use mysqldump to backup your MySQL database to local disk and have your backup software do a backup of the files on the server. That way you can easily restore your files to a new server when needed.

Good luck with your wiki!

This entry was posted in Linux, Mediawiki, Tips. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *