Tag Archives: documentation

Doing IT at Home: Good Documentation

One of the most rewarding home IT projects that I have done was to implement a system for “home documentation.”  In a business environment documentation is critical to nearly any process or department.  At home, documentation is critical too but often overlooked or approached from a completely different perspective than it is in a business, but there is no need for this.  Many people resort to special tools, iPhone apps or physical pen & paper notepads to address documenting things around the house.  I propose something far more enterprise and elegant.  A wiki.

Wikis have been around for some time now and nearly everyone is familiar with their use.  At its core a wiki is just a web-based application.  Wikis come in many shapes and forms and with varying degrees of complexity and run on different platforms.  This makes them very flexible and applicable to nearly anyone, regardless of what kind of systems you run at home.

Using a wiki for home use becomes very obvious quite quickly once the project is underway.  Documenting bills, accounts, purchases, home repairs, part numbers, service schedules, insurance information and your home network, of course, all make perfect sense and are easy to do.  The wiki does not need to be large, just big enough to be useful.  Mine is certainly not sprawling but all of my important data is housed in one, convenient place and is text searchable.  So even if I don’t know how I organized something, I can just search on it.  All of my important data is there, in a single place, so that I can look it up when needed and, more importantly, my wife can look it up and update it when needed.  It allows for simple, reliable collaboration.  And I make mine available from inside or outside the home, so I can access my information from work or while traveling.  That’s a functionality that traditional home documentation systems lack.

While there are many wikis available today, I will mention three that make the most sense for the vast majority of people.  These are DokuWiki, MediaWiki and SharePoint from Microsoft.  DokuWiki and MediaWiki have the advantage of running on UNIX so can be deployed in a variety of situations for low or no cost.  They are free themselves. DokuWiki shines in that it needs no database and uses nothing but the filesystem making it incredible simple to deploy, manage, backup and restore.  It is nothing more than a set of text files and a small PHP application that writes them.  MediaWiki is, by far, the most popular wiki option and, like DokuWiki, is an PHP application but is backed by a database, normally MySQL, making it more complex but giving it more power as well.  Many people would choose MediaWiki to use for home (as do I) because it provides the most direct experience for the largest number of businesses.  SharePoint is free if you have a Windows Server and is much more complex than the pure wiki options.  SharePoint is an entire application platform that also includes a wiki as a part of its core functionality.  If you are looking to move more heavily into the Microsoft ecosystem then using SharePoint would likely make the most sense and will provide a lot of additional functionality like calendaring and document storage too.

Running a wiki can help give meaning to a home web server.  Instead of sitting idle it can house important applications and really be used regularly.  While not a massive project having a wiki at home could be an important step to giving meaning to the home IT environment.  IT at home often suffers from lacking direction or purpose – implementing systems only like a lab and lacking real world use.  Like the PBX example in an earlier article, a home documentation wiki can give your network meaning and purpose.

Using a Wiki for Quick Documentation

If your business is anything like the businesses with which I normally deal one of the hardest items to tackle is documentation.  This can include all kinds of documentation from human resources processes to accounting practices to core business procedures to the information technology department’s system records.  Businesses need good documentation for many reasons.

Traditionally small businesses simply end up doing without key documentation and have to reinvent the wheel every time something comes up for which the people currently working have not had a chance to memorize the process.  Larger businesses often place their limited documentation into Microsoft Word or Adobe PDF files and store them away in an unsearchable file server or possibly even on paper – putting them into large, ringed binders that no one even knows exist let alone how to find necessary information within.  These are not effective processes, but there is a simple solution.

The solution is a web-based application known as a Wiki.  Most people get their first introduction to a Wiki through the ubiquitous online encyclopedia Wikipedia which is built on a Wiki platform (MediaWiki, to be specific), but this is hardly the only use for a Wiki.  Wikis are simple document repositories designed to allow many editors to easily create and modify online documentation.  The whole concept of the Wiki is about being simple and easy.  The full name, Wiki Wiki, means “quick” or “fast” in Hawaiian.

Wikis have now been around for several years and have begun to become popular in many businesses.  Wikis are generally very lightweight and there are many vendors making both open source and proprietary Wiki products in addition to several hosted services available online.  You can really pick out a Wiki based on your particular needs.  Most Wiki products are free and for the budget conscious business there is no reason to need to consider a Wiki to be a cost center.  This is a simple product that your IT department should be able to roll out for you quickly and easily giving you a documentation repository right away.

At first the idea of a Wiki is a bit foreign to most people.  On the Internet we often encounter Wikis in use for system documentation.  This is becoming increasingly popular. Wikis are often used to allow anyone to log in and make documentation changes.  This can be a good way to get started with your Wiki.  You can also start from the beginning with detailed user access controls allowing only certain individuals to post documentation in the system instead of allowing a documentation free-for-all.  Your needs will depend upon your type of organization.

What makes the Wiki concept powerful is the ease with which anyone can hop on, search for documents that they need and create or modify those documents if they cannot find the information for which they are looking.  The entire concept of the Wiki really encourages staff to make use of the format.  Lowering the barrier to creating useful documentation is the best possible way to get documentation created, and because the documentation is so easy to modify it makes it far more likely that that document will be kept up to date.

A common feature amongst Wiki systems is the idea of tracking changes to Wiki pages.  This means that if someone goes in and makes a change to a page that people using the Wiki system can view past versions of that document to see what changes have been made over time and by whom those changes were made.  This feature also makes it very simple for a system administrator to roll back bad changes if someone is not posting appropriately.

One of my personal favourite Wiki features is the idea of subscribing to a particular Wiki page either through email or an RSS feed.  The subscription model allows any staff members to be alerted to changes to documentation in which they take an interest.  These can be staff members for whom a particular Wiki page is critical to their job functions such as HR managers following changes to the corporate employment policies pages or just interested staff members who want to know when a page changes such as managers subscribing to the cafeteria’s lunch menu page or developers subscribing to a page about a particular software project’s status.

This method is a wonderful way to allow anyone to keep up with any publicly available knowledge without needing to interupt the actual process to view status.  Useful at every level of the organization and extremely simple.  So often organizations do a poor job of keeping everyone “in the loop” who needs to be and with the Wiki subscription model everyone has the opportunity to take responsibility for keeping themselves informed through whatever method is most useful to them.

As I mentioned before, there are many Wiki products available on the market today.  There are enough that choosing one is actually a rather formiddable task.  Some key differentiators between products include their use license, the data store architecture – typically filesystem based or database based, their platform dependence and their integration with other products and authentication systems.  Of course there is also the option of choosing a hosted Wiki service that hosts your Wiki online – mostly this is popular with companies using Wikis as a means of serving their customers rather than for private, internal documentation.  There are so many Wikis from which to choose that the site WikiMatrix is dedicated to helping you choose the Wiki that is best for you.

Before you dive into the world of exploring Wikis on your own I will mention a few that are rather popular and worth looking into early on in your Wiki decision making process.  Popular Wiki platforms include MediaWiki, DokuWiki, TWiki and pmWiki.  These are just the tip of the Wiki iceberg but provide a good look into the features that you should expect to see throughout your search for the best Wiki for your implementation.  The Wiki choosing wizard on the WikiMatrix web site is a great place to begin as well.  Each of these Wikis that I have mentioned thus far are available for free and rather than spending a lot of time studying their benefits you may wish to simply download one or more of them, install them on a spare server and give them a try.

In addition to stand-alone Wiki products like we have mentioned here there are also Wiki engines built into several enterprise content managment and portal systems such as Microsoft’s Sharepoint, Alfresco and Joomla.  For any businesses looking to make a larger investment in an enterprise content management system having a Wiki functionality built into that product can provide a single, unified Intranet web portal interface to serve many different internal documentation and document storage needs.

Wikis are powerful and affordable tools that small and medium businesses can leverage today, even in a climate of budget cuts and uncertainty, to document processes, ease documentation burdens and increase internal communications and efficiency.  It is unlikely that we will see the popularity of the Wiki concept wane but rather they are already beginning to take their place as a staple of the business documentation and communication process.