Documents v Wikis

I used to spend a significant proportion of my time working with documents. Nasty 100 page beasties where 80% of them felt like generic copy text designed principally with the goal of obscuring the 20% of new content you were really interested in. Consequently I developed a severe dislike of any document more than a few pages long.

The agile manifesto came along and suggested we focus on “working software over comprehensive documentation” which by some has unfortunately been taken to mean “no documentation”. Let’s just say there’s a significant grey area between the extremes of “comprehensive” and “none-at-all”.

Personally I’m aware that I fall more into the “comprehensive” camp than the other though I put this down to the fact that; for me, putting things down on paper is a great way of helping me think things through. For me, documentation is a design tool.

On the other hand, wikis…! I used to see wikis as a saviour from the hours/days/weeks spent reviewing documents and trying to keep content consistent across multiple work-products. Finally a tool where I can update in once place, link to other content and focus on the detail without the endless repetition. Something in support of the agile manifesto which endeavours to provide enough documentation without going overboard on it. Unfortunately recent experience has exposed a few issues with this.

Table below compares the two.

  Documents Wikis
For Good formatting control.

Easy to provide a historic record.

Provides a point of contract sign-off.

Easy to work offline.

Generally accessible.

Highly used critical content is maintained.

Good sharing within the team.

Hyperlinking – easy to reference other content.

Promotes short/succinct content.

Good historic record (one is kept automatically).

Against You have a naïve hope that someone will read it.

Promotes bloat and duplication.

Promotes the MS monopoly.

Poorly maintained.

Rapidly goes stale.


Promotes the illusion of quality.

Poor formatting control.

Requires online connectivity.

Low usage detail becomes rapidly out of date.

Poor sharing outside of the team.

Hyperlinking – nothing is ever in one place.

Poor historic record (too may fine grain changes makes finding a version difficult).


Hyperlinks, like the connections in relational databases, are really cool and to my mind often more important than the content itself. That wikis makes such a poor job of maintaining these links is; in my view, a significant flaw in their nature. The web benefits from such loose coupling through competition between content providers (i.e. websites) but wikis – as often maintained by internal departments – don’t have the interested user base or competitive stimulus to make this model work consistently well. Documents just side-step the issue by duplicating content.

So wikis should work well to maintain operational documentation where the user base has a vested interest in ensuring the content is maintained. Just so they don’t get called out at 3am on Sunday morning because no-one knows the location of a database or what script to run to restart the system.

Documents on the other hand should work better as design products and contractual documents which all parties need to agree on at a fixed point and which aren’t going to be turned to very often. Ten commandments stuff.

The problem is the bit connecting the two and the passage of time and decay turning truth into lies. The matrix connecting requirements and solution, architecture and operations, theory and practice, design and build, dogma and pragmatism. Where the “why?” is lost and forgotten, myth becomes currency and where the rain dance needed each time the database fails-over originates. Not so much the whole truth and nothing but the truth, as truth in parts, assumptions throughout and lies overall.

The solution may be to spend more effort maintaining the repositories of knowledge – whether it’s documents, wikis or stone tablets sent from above. It’s just a shame that effort costs so much and is seen as being worth so little by most whilst providing the dogmatic few with the zeal to pursue a pointless agenda.


Come back Lotus Notes, all is forgiven!

** Warning: Functional rant! **

I’ve spent a significant part of the past few years swearing at Lotus Notes. So much in fact that this post may be slightly bias as I struggle on a daily basis with the absence of my old adversary. Oh how I would prefer to face my old foe each morning…

Instead I face the miserable and shallow facade of functionality that is Microsoft Outlook and Lync. Yuck!

Meetings are regular missed as the pathetic reminder slides into view in the bottom right corner – cunningly; and silently, disguising itself behind another window (must have been designed for the NSA!). Scheduling a meeting is nigh on an impossibility; if you don’t get the time correct first time, start all over again. Viewing participants in a meeting? Clearly why would anyone want to…. Delegations are poorly communicated, attachments are obscured next to the subject… And so on…

I admit I don’t know Outlook very well and am a long term Notes user. Hands up! However, it seems none of my new colleagues who have been suffering this barbyesque piece of plastic crap for some time enjoy it either. Many of them have abandoned the thick (dumb) client in favour of the less abrasive web-based version and next to no-one uses Lync – it’s like shouting into the void! There’s nobody here…. Partly because it spends most of the time trying to connect, partly because it’s just shit! So shit I can feel the pulse in my neck swelling at the mere thought of it. Sametime on the other hand was the backbone of instant communication and critical to daily life. Now I have to walk across the office floor… damn it, it’s not humane, it’s barbaric, it’s just so 1995!

I was looking forward to not facing Notes in the morning, I now realise the alternative is worse. That is except for teamrooms; no teamrooms in Outlook, yeay! For that we’ve moved to wikis which are much, much better (and no, it’s not Sharepoint thankfully, it’s Confluence).

You’d have thought the dominance that Outlook and Lync have would be justified to some degree, it’s not. At the end of the day they’re just another email and instant messaging client, and not particularly good ones at that. You can pick which ever one you’re familiar with but that’s about it as a differentiator. Personally I think I’ll switch to Mutt and IRC.