Mediawiki for Business: Scaleable and Customizable Documentation

While many people hurry up projects to have them done in time for the holidays, I am in a different group. My holidays are spent working and covering the shifts of those who took time off so I spent much of this week relaxing to prepare for the long haul over the next 18 days. I did a few more courses of Javascript training, as well as found some new leads on ways to further my education. But there is not enough to write about so instead I want to talk about my work with creating and curating a Mediawiki system at my day job, a local television affiliate.

Mediawiki

Having just past the one year anniversary of our databases creation it is a good time to look back at what we have accomplished. My co-worker came to me with the project, wanting an online version of our ever changing documentation for the technical aspects at the station. I did some research and found that Mediawiki offered us a great solution to the problem. It was free (a huge plus), and offered lots of extensions and plugins to make the software work the way you need it. We brought it up in a meeting and our IT manager created a webserver on the intranet for us to host the wiki.

So far we have 557 Content Pages, 1598 Pages, and 764 Uploaded files. The main page has 4,956 page views (though the majority are probably from me), and the next highest page is 435.

Our Hosting

The server we were provided was a Windows 2008 S2 server. We installed the latest version of WAMP on the server and after tinkering with the settings connected the mediawiki database. I know we had a couple problems with the settings, but I didn’t make complete notes while we worked through it so all I can say is that we worked out our issues through lots of trial and error.

Creating the Content

I began to organize our data and lay out a plan for the best way to categorize all the content. Much was already documented in memo’s, but these were often sent out via email and printed. Months later the print outs would go missing when we actually needed them and thus the reason for creating the wiki in the first place. I retyped much of this information into the wiki, making sure to change the first person perspective to a more general form that made more sense coming from an online document.

Next I decided which pages needed more information and wrote up bullet points about every aspect anyone would need to know. The company had a failed attempt at an online Microsoft branded wiki-type software and I grabbed a lot of information that others had written up. The wiki made things much easier to sort and find so I knew that our project would be sustainable. My co-worker and I who started the project kept at it and began taking a lot of pictures to add to our documentation. Sometimes screen-captures, photos from our equipment on and off site, and hand drawn or computer graphics for diagrams and other forms of information.

Our biggest ideas for adding items to the wiki came from problems that arose in the day to day operation of the station. We would often say that would have been a great thing to have the wiki, to which I wrote up some notes and created a new page with the information. Being able to add on new content either to existing pages or new pages that are connected makes mediawiki a great tool for business technical information.

Extensions

I quickly learned that several things I wanted to do with mediawiki needed a little help from extensions. These are the mediawiki version of plugins and there is an active community of developers making these extensions. Some of the extensions we use on our site are:

  • EmbedPDF
  • FileProtocolLinks
  • ImageMap
  • MsUpload
  • ParseFunctions
  • Vector
  • WikiEditor

One of the most useful is that last one, WikiEditor, because it allows my colleagues to create content for the site easier. I don’t have a problem learning all the wiki syntax but some of them would rather use a WYSIWYG button to guide them through the process. I also love the MsUpload extension. This allows you to upload images while you are editing a page. Not only can you upload and insert the image, you can also upload as many files as you like at a time. I was having difficulty getting a bulk up-loader to work so I love the ease of this extension.

Vector made some nice modifications to the Vector skin that I set as the default. EmbedPDF allowed for technical manuals to be added to pages with an iframe. The only problem with this one was the lack of control when viewing a page on a tablet. You can see whatever the first page is but don’t have any touch controls. To work around this we made sure to provide a link to the file itself as well so if the viewer is on a tablet they can download the file to view it.

Semantic Mediawiki

About halfway through the project I came up with the idea of cataloging all the devices in our building. This means every computer, video server, graphics playback machine, everything would be in the system. We would add the name, model, serial number, software version, and location information. This proved to be a big task and one of the harder aspects to keep up to date since I’m not involved when new devices are installed or moved to a new rack.

The information is still helpful and I knew I needed some help being able to organize all the data I would be collecting. I found the extension Semantic Mediawiki, and moreover Semantic Forms. This allowed me to use the asset tag we have to audit the devices and add the details about the devices as their own search-able data.

This became most impressive when we had a bulk of the data in place and created a page with a single #ask query to view all the data.

{{#ask: [[Category:Asset_Tags]]
 | ?Manufacturer
 | ?Device_Name
 | ?Serial_Number
 | ?Model_Number
 | ?Location
 | format=broadtable
 | limit=500
 }}

This creates a giant table with each column sortable. The limit maxes at 500 so when we go over that number of total devices the search will become paginated. I also set it up so that the location and manufacturer data is a page, so they are links to a page on the mediawiki. For all of the equipment racks I took a picture of the rack and labeled each piece of equipment with a link to that asset tag detailing the devices information.

I used a similar ask query within pages. The following query uses an extra category to show the same information, but just for a particular source.

((#ask: [[Category:Asset_Tags]] [[Router_Source::CAM 1]]
 | ?Manufacturer
 | ?Device_Name
 | ?Serial_Number
 | ?Model_Number
 | ?Location
 | ?Router_Source
 ))

This extra search parameter let me show all the device components that make up Camera 1 in the studio. I repeated this for each camera right above their picture as well as other sections of the station that had several pieces of equipment grouped in one location.

SphinxSearch

My only complaint about the mediawiki up this the point was the default serach engine. It seemed like the engine was only looking at page titles and heading text and anything that was just in the copy of the page was overlooked. This proved frustrating to me and the others who I was trying to get on board with the project. I researched what options I had and found SphinxSearch which has made all the difference.

SphinxSearch added not only great search, but also the option for auto completion in the search field. When you start to type out a search it will show you all the pages that exist on the wiki for what you have typed. This made another great way for people to find new content on the site.

Like most things with the wiki I was learning as I went so it took a little while and a few headaches to get the new search engine up and running. The SphinxSearch site had a lot of great documentation as well as an active forum that helped me work though the problems. I’m not sure what the final piece was that got it working. I was doing the steps one by one for the third time and this time it took. I also set up a recurring event on the server to add any new data to the search engines database every day so it will always have all the data from the site.

Looking Forward

The wiki is not exactly where I thought it would be after a year. But the journey has been one of discovery. We came up with some of our best ideas well into the project and worked towards implementing them. We don’t have a lot of others at the station who are contributing, but many people have told me they look there first when needing answers. We hope to continue the work of documenting our department as well as adding information from the other departments.


in

Comments

Leave a Reply

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