Coding

What Can Paragons of Literature Teach Us about Writing Better Computer Programs?

Playwright and raconteur George Bernard Shaw is reported to have said, “The greatest problem with communication is the illusion that it has been accomplished.” This is true both for writing a text or giving a speech. Why? Largely because while grappling with mechanics of writing, we all too often lose sight of another important insight into effective communication enunciated by novelist and essayist Robert Louis Stevenson: “Don’t write merely to be understood. Write so that you cannot possibly be misunderstood.”

Aside from the desire that the computer not misunderstand you, at first glance there may seem to be little that unites writing computer programs and writing expository (non-fiction) texts such as essays, editorials, research papers, textbooks, etc. However, beneath the surface there is a foundational principle whose conscientious application can significantly improve both kinds of writing. Before revealing this indispensable insight, it will be necessary to set some background.

Some people have experiences early in life that seem to have nothing to do with their intended careers but later turn out to be crucial. I am one of those lucky people. Below are some personal examples of common communication errors this foundational principle can significantly help to resolve.

The Error of Inadequate Information

I graduated from UCLA in 1965 with a degree in mathematics and no intention of becoming a professional expository writer. Immediately after graduating, I spent two years as a Peace Corps volunteer math and physics teacher in Tanzania. After being stationed several months in a mud-hut village, I was posted to a rather more developed location with electricity, running water, and other modern conveniences.

A colleague of mine still in the bush had an excellent idea. Since most people in rural villages hardly ever left their villages, he thought it would be useful to take one of his brightest students on a tour of the country to get a feeling for what this new, developing nation was all about. The first stop was my place.

I asked the boy (he was 14 years old) what he really wanted to do while he was in my house. “I want to take a hot running shower,” he replied. This, of course, was not just a luxury in his home village; it was not even a possibility. A shower there meant filling a Jerry can with water, heating it on an open wood fire, and then pouring it over your head.

We had some friends nearby we wanted to visit. I took the boy into the bathroom and meticulously showed him how to regulate the butane tank (no central heating in my house), how to adjust the temperature and water flow, how to position the shower head, etc. “Now, when you are finished, I want you to turn everything off and go to bed,” I said. We then set off down the road.

About a half hour later, I thought it a good idea to come back and check on him. I went into the bathroom and I was pleased to see that he had correctly turned off both the water and the butane tank exactly as I had shown him. The light was still on in his room, so I went over to say goodnight. When I opened the door, I saw the poor kid lying on the bed with his hands over his eyes trying to sleep.

Then it hit me. I had shown him everything except the most obvious—how to turn off the light!

He of course knew about electric lights, theoretically, but he had never actually seen one. His only experience was with kerosene lanterns, which you turn off by blowing out the flame. If you have never actually used an electric light, there is no obvious connection between that button on the wall and that brilliant bulb on the ceiling.

The poor kid simply didn’t have a clue. More importantly, I simply didn’t have a clue either. As meticulous as I thought I had been, it just never occurred to me that I had failed to give him adequate information.

I had a number of such experiences in Tanzania, none of which had anything to do with lack of intelligence. This young man had survived fierce competition to get into school (the country hardly had any schools); this failure of communication had nothing to do with his intelligence, but rather my assumption that he and I shared the practice of turning a light on or off. We didn’t, so I was trying to communicate with him across a chasm of unsuspected ignorance.

The Error of Undue Deference

The situation can also go in the opposite direction, i.e. thinking your interlocutors are more aware of your subject than they actually are, because you have good reason to think so. Here are two examples.

When I was in university, a friend of mine had become an incessant proselytizer for the Theory of Evolution. He seemed able to tell you everything about it: Darwin’s discoveries in the Galapagos, order of transitional fossils, radio-carbon and other forms of radiometric dating, fossil locations in geological strata, etc.

One day I made an off-hand comment about the Scopes trial. He responded with a blank stare. I repeated the comment; he repeated the blank stare. I couldn’t believe it. He had never heard of the Scopes trial. I would have thought anyone so passionate about evolution would not only have heard of it, but would have probably memorized all the details.

If you aren’t familiar with Scopes, at the time it was billed as “the trial of the century.” In the 1920s, in the state of Tennessee it was illegal to teach human evolution in public schools. High-school teacher Thomas J. Scopes apparently went ahead and did so anyhow. He was subsequently brought to trial for his malfeasance. The prosecutor was William Jennings Brian, former U.S. Secretary of State and three times candidate for president. Scopes was defended by celebrated attorney Clarence Darrow, a leading member of the American Civil Liberties Union.

The upshot of the case was Scopes was found guilty, which was to be expected. However, the trial itself riveted the nation and brought the teaching of human evolution (and evolution in general) in schools to the forefront of public attention.

You can understand my astonishment that my friend, who seemed to know everything there was about evolution, was unaware of this pivotal historic event. It would never have occurred to me to even think he might not know about it. It seems anyone, no matter how apparently learned, may have a gaping hole in their knowledge.

My second example occurred in my capacity as a communication consultant. Early in my career I was asked to publicize the existence of a new chemicals trade association dedicated to promoting the interests of fatty acid producers. The association had spent its first three years getting organized and felt is was time to announce itself to the world. It was particularly seeking recognition by what was then considered incontestably to be the world’s leading professional chemicals magazine.

I prepared a press kit that contained all the standard items, e.g. the association’s statement of purpose, a short history, current and projected activities, profiles of the officers, etc. I also included a two-and-a-half page description of the nature and chemistry of fatty acids.

My client was shocked. “This magazine is aimed at professional chemists working at the highest level. This piece on the fundamentals of fatty acids would be an insult to their intelligence. Get rid of it!” I argued the work had already been done. Putting it into the press kit would cost nothing. If the editors of the magazine feel that it is of no interest to their readers, they will simply throw it away. That’s what editors do.

Reluctantly they agreed. A piece on the association appeared in the magazine two months later. Everything that had been printed was a reduced and revised version of what was in the press kit, because condensing is also what editors do. The only thing that had been printed verbatim was the “insulting” piece on the fundamentals of fatty acids.

Why? I can only guess. The magazine was indeed for “professional chemists working at the highest level.” However, most of them were not working with fatty acids and probably hadn’t had anything to do with fatty acids since their student days. Therefore, the editors probably felt that a brief reminder of the fundamentals of fatty acids was appropriate.

Aim for the Lowest Common Denominator

Someone once said: “Nothing is so simple that it can’t be misunderstood.” So what is this essential writing principle mentioned at the beginning of this article? It’s quite simple. Whatever you are writing (a computer program or a piece of educational or instructional literature): Always aim for the lowest common denominator.

In other words, assume your readers are intelligent but know little or nothing of the topic about which you wish to enlighten them. Then build up from there.

But the objection can be raised: “Isn’t aiming at the lowest common denominator patronizing?”

Yes it is, but mainly in the mind of the writer, not the reader. The fact is, no matter how hard you try, you can never be certain what each individual reader knows and doesn’t know about your topic. What you can be certain about is that if you say something they don’t understand, you will lose some (if not all) of their attention. This is especially true of technical subjects.

For example, computer programs are often more than a way of controlling a computing machine—they communicate computational methods to others. Good programmers include plenty of comments in their programs so that future programmers (or themselves) can reconstruct what the program does when it is time to correct a bug or make a change. Less conscientious programmers are often surprised that a year or two later when they revisit an old program to find bugs and make improvements, they cannot recall their train of thought when they wrote the original program. Thus, it is much harder to find the bug or decide how make the changes.

Updating becomes so much easier if you have been generous with your comments and have recognized your future audience, including yourself, needs to be approached with the lowest common denominator when describing the intent and organization of the program.

Whatever you may be writing (computer program or otherwise), it is always necessary to make some assumptions about your readers’ level of understanding. However, you should consciously and conscientiously try to make as few as possible. Those readers who are already knowledgeable about what a particular section of your text is saying will either skip it or appreciate the reminder. Those who are less knowledgeable will be grateful for your clear explanation.

Throughout my more than 40-year career as a professional communicator, I have produced news releases, sales brochures, speeches, instruction manuals, science articles, training manuals, etc. I can recall no occasion where someone complained that my text was “too simple.” However, I distinctly recall several occasions where someone said, “I thought this subject would be extremely difficult, but I understood everything you wrote. How did you do it?”

Now you know. It was by consciously and conscientiously aiming for the lowest common denominator—and then some.

For specific techniques to help ensure that you achieve the lowest common denominator and then some, you may wish to read: “How Crafty Word Order Can Instantly Improve Your Writing” and “The Three Acid Tests of Persuasive Writing.”