blogs.conchango.com

welcome to the conchango blogging site
Welcome to blogs.conchango.com Sign in | Join | Help
in Search

James Dawson's Blog

Word Documents or Wiki?

I've talked about why I like Wiki as a documentation medium before, however, today I had a discussion with one of my colleagues where we were considering the merits of such an approach versus the traditional word processing document - incidentally, in this case 'discussion' is not a euphemism for argument!

My belief is that certain people take some kind of comfort in being handed a tome-like Word document as a tangible deliverable from a given piece of work - and worse still, make a judgement on whether the work was value for money based on the page count - in my experience the usefulness of a document is often inversely proportional to its length!

The problem is, in my opinion, producing documentation using traditional word processing tools seems to encourage verbosity - you feel obliged to include such elements exposition, context, and background regardless of whether they are really needed to get your message across. On top of this, I often find that the richness of the formatting functionality contained by such packages can be a distraction from the actual content.

All you adept Word users (I consider myself in that bracket - 3 years working in a Law firm's IT group leaves it mark), how may times have you found yourself battling with some shonky template that just refuses to number or layout your headings properly? (OK, I guess that's just me then)

My point is that by stripping the formatting and layout features back to the necessities you no longer get caught up in trying to bend the tool your will, instead you just get on with producing the content - back in the dot com days there was a phrase banded about by start-ups as to why they could make it big - 'Content is King' - I believe that this is certainly truer for documentation than it was for them.

Don't get me wrong, there will always be a place for the traditional word processing document as the appropriate deliverable, but I think only for specific types of work. Typically, I consider these to be reviews or analysis-oriented work where the end results are essentially static and represent a state of affairs at a given time.

I believe most technical documentation should be treated as 'living' and updated as necessary - an out of date technical document is next to useless, and 70 page word documents just don't get habitually updated. For me, that's why Wiki-based documentation is so powerful - the latest version of the content is always available and can be collaboratively updated with minimum friction to your actual task in hand. For instance, following a set of procedures (perhaps written by someone else) and finding an error or omission - you can quickly add or amend the information and get back to following the rest of the procedures, and your learning's are immediately available for the next person.

It's no panacea of course, a key drawback I have hit with using this approach (other than convincing clients that this type of documentation is as good as the 'real thing') is when you need to get the content into a hard-copy or any other offline form - if you have structured the content across a number pages (i.e. due to length), with perhaps a table of contents page as the entry point, you have to visit and print each page individually.... if only there were some kind of recursive print function.....

Published 09 August 2005 23:10 by james.dawson

Comments

No Comments
Anonymous comments are disabled
Powered by Community Server (Personal Edition), by Telligent Systems