Software is knowledge

People screaming about software engineering were pulling the wool over our eyes and trying to make a quick buck, all along, as we all suspected when we attended those boring software engineering classes in CS courses.

Robert Glass got it right. Software is NOT an artifact of engineering. Making software is not like making a bridge.

Software is an embodiment of knowledge. Executable knowledge. Knowledge that when pasted over some silicon and stimulated with electricity can cause things to happen. By itself very little beyond flipping voltage levels in areas of said silicon. But give it some tools (like a serial port, cable and lcd screen) and it can communicate. Give it more tools (serial port, cable, robot arm) and it can create physical changes in its environment.

Yeah, you got it. Software is less like a scalpel, more like a doctor.

Why the sudden light?

Well, I was trying to document high-availability solutions with MySQL. When going through the nitty-gritty of MySQL Cluster’s limitations (no offense intended: it is probably a good product; I am not dissing the software) it occured to me that they warranted noting down, so that my team would not have to read so much should they deal with MySQL Cluster. I found myself writing a short note with a link to the original page for details, because I felt that I could not tell the whole truth in a shorter way, and copying and pasting would be a waste. So, my documentation is a little more than some summary notes peppered with links to the full documentation.

Anyone reading any code that tried to deal with the limitations above—written in an arguably already readable language—would still scratch their heads at why some weird stuff was being done. There would have to be comments explaining why this was done. The comment could be just a link to the MySQL documentation page. Or, it could have the full explanation, with the MySQL version in which said limitation lurked. Or both. The person reading the code would have to understand the documentation before they could say they understood the code.

The point is that: if there is good documentation about some topic, I can do little than point others to it and say “this is important”. The documentation is the communication.

And the more important point is: you cannot claim to have understood a software unless you understand its intention and motivation. And in the above case, the motivation means reading the documentation. Most times, reading documentation means you come back with knowledge. In other words, to understand the software, you must, well, understand. Err.. I mean, you must acquire the knowledge the original developer had when creating the software.

Which brings me to a wicked question: the reason I was writing the original notes about clustering was so that not everyone in my team has to know the nitty-gritty and just know enough to design and write code to be handle clusters if we decided to use clusters. But it looks like no one can actually decide if the code will be right without having read the full documentation anyway.

What about code? That’s worse. You now must understand the intention of the code. Then you must understand the motivation behind the code. To do that you must read the documentation.

Software is knowledge.

And my documentation is little more than a reminder note or a collection of related links.

Post a comment or leave a trackback: Trackback URL.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: