Monday, November 21, 2005

Is documentation really such a pain?

Since the discovery of blogs and wikis, I have never found that much fun in documentation. There is a certain element of funlyness, if there is such a word, that makes you feel all soft inside. Ooooo.

I'm sure everyone struggled to try to put their homepages online. I remembered when I first had to put up. Only managed to fix it today, although I've been wanting to do something with it for ages but never got about to it. This is the first brilliant example of how blogs make documentation easy. It's so much easier for me to just focus on the content on message instead of worrying about how to structure the page into the rest of the site. The days of large number of webmasters are numbered. Blogs naturally being great for journals and historical references.

Once we get into the area of categorisation and versioning, I would highly suggest using a wiki. There are quite a few wikis out there to join in. Its a great opportunity to put your valued knowledge and learn a thing or two. Everyone has tons of weird 'useless' information in our brains, wouldn't it feel better if we just 'documented' these somewhere?

Especially when faced with improper, outdated, unused documentation and technical people who refuse to document tips and tricks based on no proper category in a word document or website, knowledge gets lost.

One day, after getting pissed with the state of documentaion, I suggested, "Lets start a wiki". Oddly enough, the response was "Whats a wiki?". Things progressed and I installed openwiki, the most idiot proof wiki I can find that runs on windows having a simple ms access backend with ASP files that can be published on IIS.

Sometime after I implented the wiki, someone asked me a question and I responded with "check the wiki" and not so oddly enough, the response was, "that sounds like a technical voodoo god?" :P

My opinion on what makes a successful wiki; Give and you will receive. It is preferable to give more information especially when starting out. As a general guideline, documentaion should take as much time as performing a task, unless when performing the task, you spend half the time twiddling your thumbs in wonder.

With both these tools, documentation is easy. Go forth and plunder.


NabeelC said...

I totally agree with you. Blogs and wiki lets you worry only about content. It totally takes making a website easy. Once you set it up, all you have to worry about is content. ISU website backend is built on the concept of Blogger.

The only thing I find inadequite about Blogger is trackback. If you write a post, you should be able to see who else wrote a reply to your post on their own blog. This function is available on Movable Type but they charge you and you need to configure it or sign up for TypePad.

Can't wait for blogger to do it. You would think Google would move faster than this to meet market demand, but seems like they have becomes slower after going public. Its such a shame. I don't think they have realized anything significant in the past 1 year. Last significant release was Text Ad and Gmail. Everything else was a small insignificant ripoff of compititors. In comparison, Yahoo has flickr, Yahoo Maps beta (the new one)

Anonymous said...

The wiki idea is genius! That's why you get the big bucks you techno stud, you!
All bow before the Wiki deity and its high priest, the machinehead.

Wati said...

Hi there, saw your comments on my blog. I've fixed the broken links. My mistake.

Thanks ;-)

Wati said...

BTW, I rely on wiki a lot for the simple reason that you can get information quickly and accurately, all in one place.

Melven said...

I'm glad to see that wiki is such a popular tool, I think a great use for it will be in govenment.

Its odd that most large government affiliated data centers or institutions dont use it and find it difficult to implement a consolidated form of documentation.

dead pi

Well, I guess it has to happen at some point. the home automation raspberry pi has died. Much to do with the stupid Strontium mini SD card. ...