The Skies Are Not Cloudy All Day

Years ago, I worked in the Quality Assurance department of an insurance software company. The company’s management had outsourced code development but kept the Sales and Marketing, Business Analysis, and Quality Assurance Departments in-house. I performed two roles in Quality Assurance: One was developing and documenting standards, policies, and procedures for software analysis, development, and implementation. The other was testing code written by our development partner. In performing the latter function, I created software tests based on my company’s business specifications and then executed the tests against the vendor’s delivered code.

Once, I ran into a problem testing some new code. In my understanding, the program was to process data from two input files—let’s call them File A and File B—and, in the analyst’s words, write errors found on the input files: “to the applicable error log file.” Along with valid test data, I intentionally created errors on both input files. When I completed the test, I expected to find error records written to an error log for errors on File A and to another one for those on file B. I didn’t. I checked my files, reread the specs, reran my test, and got—SURPRISE—the same results.

At this point, I met with the vendor’s on-site coordinator to review my test results. I told him that the new program failed to detect and write input errors to the applicable error log. He brought up the database and said, “No, you’re wrong. The errors are there.” I asked him where. He said, “In the Applicable Error Log.” The vendor’s programmers had created a file in the database named “Applicable Error Log.” It contained the input errors combined in one file. At this point, I realized, in words spoken by Paul Newman in the classic movie Cool Hand Luke, “What we’ve got here is failure to communicate.” [I should point out that in the film, Newman was shot right after saying that.]

The vendor and I disagreed about the meaning of the analyst’s words “applicable error log.” Faced with the possibility that I might have misunderstood the specifications, I met with the business analyst. She told me there should be two output error log files, one for errors on File A and another for those on File B. What, she asked, did I think “applicable” meant. I went back to the on-site coordinator and shared with him what the analyst told me. I asked him to fix it, to correct the code, so it matched the specifications. He refused, initially. He argued that his team had developed the code precisely as specified in the analyst’s document. They had written all errors to a file name “Applicable Error Log.” 

In the end, the vendor modified the software to create two output error logs. And my company paid for the change. As a result, my supervisor decided it was time to update our QA document addressing the writing of business specifications, including a new section about the cost of ambiguous specifications and the need to eliminate, insofar as possible, textual ambiguity. I was given the task of reviewing the draft of the updated business specifications document.

My review was going along pretty well, minor typos, less than felicitous phrasing, that sort of thing when I hit the following guideline: “Specifications shall be written such that they can not be interpreted.” Well, I felt pretty sure that what the author wrote was not what she meant. Indeed, she had meant something along the lines of, “Specifications shall be written such that they can be interpreted in only one way.” I met with the document’s author, who understood my point and made the necessary correction. I also suggested that analysts should include flow charts or diagrams to elucidate the specifications in some cases. In the example above concerning two input files and an “applicable error log,” we could have avoided wasting time and money by including a diagram showing Input Files A and B and Output Error Logs A and B.

While most people will understand and agree with eliminating ambiguity in technical or business documents, they will argue that it often serves a good purpose in fiction, poetry, or even religious writing [After all, God’s ways are not our ways, God’s thoughts not our thoughts; why should we think that we can nail down the meaning of Divine discourse?] Some might even say that ambiguity is a necessary feature of poetry. I don’t see it this way. Ambiguity in any discourse is, in my opinion, a problem. I need to add that this is correct, assuming the author’s intention is communication, that is, to get what they have in their head into our head. Hopefully, poets do have that desire just as much as do business analysts.

Monroe C. Beardsley (1915-1985), the late American philosopher of art, is best known for his work in aesthetics. When reviewing the second edition of Beardsley’s Aesthetics, Mary Mothersill, Barnard College of Columbia University, wrote, “of the twenty or thirty textbooks in aesthetics that have appeared in the past quarter century…[this] is far and away the best.” 

Beardsley was a devoted practitioner of analytic philosophy. Analytic philosophy emphasizes language, clarity, and logical rigor in arguments. It should be no surprise that in addition to his work in aesthetics, Beardsley authored books like Thinking Straight: A Guide for Readers & Writers and Philosophical Thinking: An Introduction. I heartily recommend Thinking Straight for any writer—technical, fiction, prose, or religious.

I would like to briefly address the idea that ambiguity is a desirable quality of non-technical writing, like fiction, poetry, and religious writing. I will draw on Beardsley’s work to do so. Professor Beardsley understood that part of the richness of poetry is the product of word connotations, the feelings or thoughts that words evoke apart from, or in addition to, their literal meanings. The connotations that the words in a poem evoke, and not any ambiguity, account for a poem’s multi-layered meanings. In Thinking Straight, Beardsley writes, “Poetry is…the best place to study word connotations. What makes a poem a poem (not just verse) is in part the complexity, and coherence, of its connotations.” (p. 71). Later on, he points out the differences between great poetry and clear prose. Note that for him, poetry and clear prose exist on a scale.

It is useful to think of a discourse in terms of the degree to which it compresses its meaning. We can thus form a rough scale, without any insinuation of praise or blame. At one pole we have the kind of poetry that yields a rich supply of connotation and suggestion: for example, Shakespeare’s sonnets. At the other pole, we have the sparest and leanest sort of discourse, characteristic of much of the best philosophical and scientific prose: for example, most of the writings of Bertrand Russell. At this end, the terms are chosen and fitted together to keep down connotations, and the sentences are arranged to minimize suggestiveness. What is meant is by and large explicitly, clearly, and unmistakably stated.

Beardsley, Thinking Straight, p. 83.

By “discourse,” Beardsley is referring to either written or spoken communication.

Music was my favorite class in grade school. I especially enjoyed the days we sang together. I liked songs about America, the West, and cowboys, like Clementine, Home on the Range, and Red River Valley. In Thinking Straight, Beardsley uses a line from the first stanza of Home on the Range as an example of ambiguity. Can you find it? Once you find it, can you think of a way to remove the ambiguity and retain the rhyme and rhythm of the verse?

O give me a home where the buffalo roam,
Where the deer and the antelope play;
Where seldom is heard a discouraging word,
And the skies are not cloudy all day.

Here, I had room to give only a taste of Beardsley’s thoughts on admirable prose and poetry. If you have time and interest, I believe you can learn much about clear writing from Professor Beardsley, whatever you are writing.

All the best,
Gershon