Wikis – The Best Tools for Documentation and Specifications

Writing documentation and specifications for developers is a big part of my day job.  Writing clear, concise documents is very challenging.  It’s one thing to write notes for yourself, quite another to explain complex systems and the desired outcome to others.  Not only is determining a format or standard way of writing things important for clarity, but so too, are the tools one uses to communicate.  This post will focus on the tools for sharing  documentation and specifications.

The standard documentation and specification writing tool of most businesses is Microsoft Word, Visio for diagrams, and Excel for spreadsheets — or other similar tools such as Open Office, Apple’s Pages, Numbers and the Omni Group’s Omnigraffle.  I have used all of these, but found each lacking in one fundamental way; they make ongoing “knowledge transfer” difficult, if not down right impossible.

DokuWikiWhen I say “knowledge transfer”, I mean the ongoing care and feeding of systems, troubleshooting a problem or implementing an enhancement to an existing system, or set of systems.  Unless the developer, project manager or end user knows where to find the original documentation, be it a specification or write up of a process, it is much more likely that these individuals will seek out any human specialist thought to know about this program or system first and ask for a verbal “download” and knowledge transfer meeting.  Not really something that is efficient in the long run as it relies on the ongoing staffing of these so-called specialists.  I for one don’t want to be the first stop for questions about systems and programs I have documented in the past — I want my documentation to be the first thing end users turn to for help and guidance.  Document management tools such as SharePoint, LiveLink and others help by providing a search function, but I have yet to see anything beat a simple wiki for knowledge transfer.  (My favorite wiki being DokuWiki.)  Hands down, they win out.

Let’s compare using SharePoint and Word/Visio/Excel to using a wiki to better clarify this comparison.  When using SharePoint, an end user can search the contents of the SharePoint site and get a really excellent search results set showing screen previews of Office documents, filters for last updates and more.  (Truly, the search results in SharePoint are great.) However, if all of the information is stored in a file, the file must be downloaded, or at best viewed online and edited with browser plugins.   A large dataset of Office files also becomes something that must be indexed regularly and is processor intensive.  What’s more, there’s ample opportunity for the document to be shared with others outside of the document management tool which may be seen as beneficial to some people, but for me is tantamount to storing the same data in several places with things quickly getting out of sync.

If all of the documentation is done directly in an easy to read, highly searchable wiki page, then even the questions the end user may have can be added directly in the document with updates and improvements to the documentation being done by the community of users.  Every wiki I’ve ever seen tracks changes well and is extremely searchable – this is exactly what wikis were created to do.  There is no additional application needed, you just use a web browser.

So why not use a wiki for both your documentation, specifications and runbooks all in one fell swoop?  If even somewhat organized into separate namespaces, a single wiki can provide an organization with a very powerful knowledge transfer tool that doesn’t require any desktop application or special licenses.  Diagrams are really the only tool one needs an application for to create outside of the wiki.  (I would also argue for using a diagraming tool such as Open Office’s drawing tool, Visio or Omnigraffle – a future post on diagraming seems like a good idea.) A single reference point for all documentation helps prevent fragmentation of the process documents and helps facilitate a culture where knowledge transfer is done routinely, and information hoarding is no longer the norm.

[I’ll be updating this post shortly with some tips for how better to construct a wiki page, too.]

 

DokuWiki

DokuWiki

If you’ve not used a wiki for documentation before, I would highly recommend you consider installing DokuWiki and giving it a try.  Rather than putting specifications, help desk notes or anything that requires versioning, updating and needs to be clearly understood by all members of your audience into a text document (or God forbid – Word!), think about using a wiki for this purpose.  Wikis are easy to update, track all changes, are highly searchable, and can have links placed for related topics in a snap.  Wikis also can be updated by the user themselves allowing more than just the author to control the wording and depth of the description.

Last week, Patagonia paid for me to spend a day training staff from VCCool how to use a new Joomla! based website I had built for them as part of an Enviro “Miracle” Grant from the company.  To make the presentation lasting and purposeful, I put all of the training information into a wiki I had installed.  Having used wikis for documentation and help guides within Patagonia for the past 6 years, I really couldn’t think of a better means of disseminating information.  Now the VCCool staff can update, improve and contribute their own voice to the guides for running their website and their organization.

There are several great wiki open source projects out there today, and I’ve tried quite a few of them.  For me, DokuWiki is the best of breed.  It runs without the need for a database, is fast and easily updated, has a clean, easy to read layout and is a well supported project.   Until something better comes along, this wiki is my primary tool for internal documentation and reference creation.

TiddlyWikis

We’ve long been a strong support of wikis.  (Especially DokuWiki — look for a future blog post on this great open source tool in the future.) Wikis are great tools for being able to quickly add test, a link hierarchy, images and links to documents by even non-technical people.  Most also provide a version control system.  Perhaps their biggest strength is in the ease of searching for terms and usage.

All of that being said, a hybrid of this great tool is TiddlyWiki.  Described as a “wiki on a stick”, or a reusable, non-linear personal web notebook, these little single page wikis have a lot of potential as documentation tools and more.  For several months after first discovering them, Monkey Pirate GTD I used MonkeyGTD (MonkeyPirateTiddlyWiki+GTD) which has a “Getting Things Done” organization to it.  Having just had training in the GTD method, it was my search for a tool to use with my new understanding of GTD that led to the discovery of TiddlyWikis.    If you’d like to sample all kinds of different TiddlyWikis, go to TiddlySpot.com.

What I like most about this single page tool is the speed that it runs.  No need for anything but a web browser and a place to store your file.  Very slick.