Making things clear

I have just read an interesting article in TechRepublic about the usual problem of explaining IT technical concepts to a "normal" user. It is a challenge that we, IT professionals, encounter frequently in our work: how to make clear to the user the correct meaning of a complex IT subject that we are trying to explain...

One of the biggest problems we face nowadays is the vulgarisation of IT. Many decades ago, when computers were still regarded by the users as a mysterious box full of wonders, it was much easier for us, the experts. Users didn't fool around with their equipment before finally giving up and look for help from an expert, they came immediately to us for assistance, and this made things a bit simpler. Nowadays, everybody seems to be an expert in IT and likes to show off to their friends how able they are in handling the, sometimes very difficult, problems they encounter when dealing with their computers.

In the article I mentioned above, the advice is to make use of analogies in order to make things clear to the user. It is a very good approach and I have used it countless times with success. But be careful, trying to clarify an issue with some sort of childish comparison to a graduate may appear to that person that you are being contemptuous. The opposite, using an analogy that is not within the reach of the person in front of you, is also pointless. Therefore, a very important consideration is that in order for the analogy to work, you must look for something that is familiar and appropriate to that kind of user.

IT professionals have long understood this challenge and a lot of issues are already being put forward in such way that they directly refer to an analogy that is easy for the user to grasp. Take the case of viruses, for instance: a computer virus doesn't need further explanation to a user, he understands immediately the need to avoid having a malicious piece of code inside his computer in the same way we don't want to get a virus inside our bodies. If he does something about it, that's another story, just like people that still refuse to get the flu vaccination. But this stubborn behavior cannot be changed, it's part of human nature...

Take a look at the article yourself and find out which analogies you find useful or which ones you have been using that are not there. The main point is: nothing beats a good analogy as long as the analogy doesn't seem in any intellectual way unsuitable to your audience...

To comment or not to comment

I was just following an interesting thread in Slashdot about commenting code. You can take a look if you want: Myths About Code Comments.

I think that the controversy about this subject comes mainly from people who are not developers and, therefore, cannot possibly have a clear opinion about it. Of course, if I am a manager buying a product with source code, I will make sure that everything is well documented before I pay for it. However, software is not like an object that you buy with a user guide that will always be relevant because the object will never change until it falls apart. With software, things are quite different: in general, if one has the source code there will be changes applied to it.

The big trap of extensively commenting code is that there is no guarantee that someone will update it to reflect the changes brought to the software afterwards. Then we will have the worse situation where the documentation does not correctly describe the code. It is worse because it could be misleading and cost you a lot of hours pointing to the wrong direction when you're trying to solve a bug.

As a developer I always stayed away from documentation of code that has been through several cycles of modifications, much preferring to concentrate on the code itself and trying to understand it as much as possible. Because of that, I tend to agree with those who preach that code should primarily be self-documented.

Once upon a time I was called to program some expansions to a Unix device driver for TTY terminals. The code was voluminous and I could not see much documentation around it. To make things worse, I had just started programming in C... Nevertheless, I was able to successfully perform the task in the allocated time and this I owed exclusively to the developer who not only wrote excellent self-documented code but was also very tidy in formatting all the source lines, making the code very easy to follow.

To cut a long story short, I would say that if the customer demands documentation, you should do it in the way that pleases him, mainly because I assume you are doing developing for a living. However, always take into consideration your fellow developers: write clear, well-formatted and self-documented code, avoid complexity and embrace simplicity, and drop a useful comment here and there where it is really needed. Above all, use separate lines for those comments, never put them in-line with the code, they will disappear indiscriminately when changes are made...