Journal entries
Le Bon Journal



Bon Journal

I cracked the code

What a relief it is to figure out the inner workings of a black box! Without proper documentation or instruction manual, I had to rely on trial and error and logic.

Some years ago, I got landed with a task that no one else wanted to attempt. It was an archaic in-house software that had evolved over time but still mission critical for the business. I painstakingly went through each line of code trying to determine its purpose and how it fitted in the overall scheme of things.

After much testing, I finally pieced together the jigsaw puzzle. The resulting documentation was over a hundred pages long. Needless to say, it remained a black box for everyone else. Who would want to read the documentation I wrote?

I learned over time to build simple models that people can understand. Simple to build and simple to use. Transparent. Welcoming. A model, by definition, should be a simplified version of reality, not a more complicated one. However, model builders often forget about keeping it simple but pride themselves in building complex models that only they have the stamina and the interest to understand and use.

Having cracked the javascript code, I now have to document it. The challenge is to explain it in such a way that it's not necessary to crack my documentation!

9 July 2004 Friday

Related links:
Unofficial pointer
Computer haikus
Victim of technology
Like this entry?
Your comments to editor:
Your e-mail address:
Tell your friends about this Bon Journal entry:
Your name:
Your e-mail address:
Your friend(s): Be sure this field is filled and correct!
 (please separate additional addresses with commas)
Your message:

Anne Ku at Ilp in May 2001
Anne Ku

writes about her travels, conversations, thoughts, events, music, and anything else that is interesting enough to fill a web page.
Support the Bon Journal by keeping alive and free. Find out about Sponsorship.