Working a Wiki Into My Development Workflow

At work we use a wiki (MediaWiki) for internal documentation. Wikis are something I had some previous experience with at my old job (obviously I have had experience with sites such as wikipedia.org) but it wasn’t something that more than a few people were contributed to and it was really never fully embraced. Part of lack of acceptance was that it was an MS SharePoint wiki and keeping with SharePoint’s MO, was not very user friendly and therefore did not lend itself to easily being incorporated into everyone’s workflow. If you have ever had any experience with a wiki you know that they are only as good as the frequency with which they are updated. This means that it is crucial for the wiki itself to become a regular part of your ever day development workflow. Doing this will have tremendous results and an incredibly positive impact on your documentation and developer collaboration.

Learn the Syntax

The first step for me was to learn the wiki syntax. Sure you could use the built in WYSIWYG (What You See Is What You Get) editor but as with any such web based editors, they can be inaccurate and clunky. The true advantage to learning the syntax is the speed at which you will be able to make updates. Never letting your hands leave the keyboard is always a faster way to get work done on a computer. Honestly the syntax isn’t that complicated and once you get it down and use it all the time it will be second nature. The best place to learn about the syntax is from the wiki’s documentation which is almost always a wiki itself. For example MediaWiki’s documentation is excellent, content rich and full of examples.

Starting a Flow

The next step for me was to make sure I had quick access to the wiki. I wanted to be sure that if I ever had a question about something that I was working on or that just came across my mind, looking for my answers would be just a few keystrokes away. To do this I utilized the open search protocol exposed by MediaWiki and the built-in search support in Google Chrome. Have you ever notice that if you start to type in a URL such as wikipedia.org or imdb.com into the Chrome search bar and then you press the tab button the search bar changes to include a blue box with a magnifying glass icon and text “Search IMDB.com”? This functionality is made possible by the open search protocol which is essentially providing instructions to Chrome on how to perform a search on this specific site. The fantastic thing about this is that once you have done a search like this you can now add the site’s search engine as one of your browser default engines. To make it even easier for you to use you can provide a short name version of the search engine so that instead of typing “imdb.com+TAB” you can type “imdb+TAB”, for example. Combining this with ensuring that you are “always logged in” to the wiki, means that searching the wiki is only a few keys away.

Now when I am working on something that I either need more information on or want to record some information about I do a quick search for the topic in the wiki. If I find what I am looking for, Great!, if not I can easily turn the search term that I used into a new page so that the next time I or someone else searches for the same topic the information is available. That being said I try to put some effort into locating the information on another page and if my search term is perhaps not what I would like to name the page I create a redirect or “move” the search term page to a more appropriate location. Additionally if I find the information I am looking for I might add the search term I used as a new page which redirects to the correct page. This often results in searches that I type in chrome opening a page directly rather than display the wiki search results.

So far this approach has been very effective. More than anything, the fact that I update the wiki on an almost daily bases means that everyone else in the department is also spending more time in the wiki performing their own updates.