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.]


Things and Evernote – tools that go together

EvernoteTwo tools I live, eat, and breath using are Things (from CulturedCode) and Evernote. I use Evernote for notes including captured images, documents and links and Things for task management using Getting Things Done (GTD) methodology.  Things IconIn theory, each could stand alone and I suppose I could get along with Evernote alone, but sometimes it’s better to not stretch a tool to be used beyond its primary purpose.

Evernote is ideal for note taking and capturing, well, anything.  Use your camera on your smart phone or tablet to capture white board meeting notes, or a page in a book (Evernote will use OCR software to make this text searchable, too), or a group of people you just met — anything.  Take notes on your desktop, phone or tablet – or use a web browser to login to the web app version.

The free version does all I need it to do.  I can take a photo of each of our car’s license plates and know that I’ll never need to look it up again or remember it.  I can take notes on my iPhone, company iPad or laptop — it all gets synced and is available to me on any device I need it on.  I can search the data, tag it and organize it in any number of ways.  If you love GTD like I do, you’ll quickly understand how this tool is the perfect one for capturing all the data you need to sort and organize.

Things is light weight and simple for me to drop my to-do lists into as well as do a mind sweep of all the various “things” my brain is over analyzing and trying to remember.  (GTDers, you know what I’m talking about here.)  I can capture a task quickly on my iPhone and then process it later.  If I tag it, my tags can reference Evernote tags, too.   Just like Evernote, it has a custom iPhone and iPad app, too, because mobile devices are used differently than desktops or laptops — and everything syncs across all of my devices.  Things is not free, like the basic version of Evernote is, but I’ve never regretted buying the desktop and iPhone apps once.

If you are looking for a way to increase your GTD adoption, I really recommend using both Evernote and Things together.