Skip to main content

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 melven.com 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.

Comments

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.

Popular posts from this blog

Multiple Broadlink RM mini 3 integration using MQTT

Broadlink now has quite a lot of integration options almost out of the box. If you enable Broadlink IHC, you can directly link it to Alexa by giving the device a unique name.

There is a homebridge plug in for homekit integration but I haven't tried or tested this. https://lprhodes.github.io/slate/

I wanted to put the device in domoticz so I can have more control over what can trigger my broadlink. I decided to use broadlink-mqtt for this, which is a fairly easy method to trigger from any source.

Setup Instructions for broadlink-mqtt

1. git clone https://github.com/eschava/broadlink-mqtt

2. vi /home/pi/broadlink-mqtt/mqtt.conf

3. Update the mqtt.conf file with the device type set as multiple_lookup

device_type = 'multiple_lookup'
mqtt_multiple_subprefix_format = '{type}_{mac_nic}/'
4. Start the python script and check that it started and detected all the RM devices.
Check the log file to see what the IP / MAC addresses are. DEBUG Connected to RM2 Broadlink device at …

Fibaro HCL Virtual Device Slider

How to setup Fibaro home center lite (HCL) slider for virtual devices.

As the Fibaro HCL does not support LUA. The question was how to update the number value of the slider to send to the HTTP string. Thanks to this site which is a really good reference https://www.vesternet.com/resources/application-notes/apnt-88/

The 2 use cases here are;

Sonos HTTP API Volume

To allow for volume control for all Sonos devices, add a virtual device with the IP address for SONOS HTTP API and specify the default port to 5005. Create Slider and put the following text into the string.

GET /volume/_sliderValue_ HTTP/1.10x0D0x0A0x0D0x0A


Domotiz Virtual Devices

GET /json.htm?type=command&param=switchlight&idx=XX&switchcmd=Set%20Level&level=_sliderValue_ HTTP/1.10x0D0x0A0x0D0x0A

Replace XX with the device ID.

Restart Fibaro HCL when it stops working automatically

It seems that the Fibaro HCL seems to hang every now and then. Instead of trying to restart it regularly, which doesn't really work, as it's almost impossible to predict when this will happen.

This method checks that the HCL is actually running and in the event it stops working, trigger a script that will restart it.


1. Get a non Fibaro controlled power plug and scripts to control it.

I used a wifi smart plug, TP-link HS100 and downloaded the scripts from

https://blog.georgovassilis.com/2016/05/07/controlling-the-tp-link-hs100-wi-fi-smart-plug/

2. Create a bash script to restart the Fibaro, e.g. restart_fibaro.sh

#!/bin/bash

ip_addr=
scripts=

$scripts/tplink-smartplug.py -t $ip_addr -c off
sleep 10
$scripts/tplink-smartplug.py -t $ip_addr -c on


3. Create a test global variable in the Fibaro HCL

Go to the variables panel and create a test variable, e.g. Test


4. Add a cron entry to test that the Fibaro API is still working and restart if it's not.

The cron script is scheduled ev…