Quote of the Day
Do not forget what is being a sailor when you become a captain.
— African proverb
Figure 1: Newton's Pincipia is my vote for the world's most obscure writing. (Source)
I had a discussion with one of my engineers this morning about documentation and our company's standard of readability. When I was in school, I always tried to write so that I could be understood. It was while working as a US Navy contractor that I discovered that I need to write so that I could not be misunderstood. This lesson was drummed into me by a safety engineer -- a man to whom I am in debt. His writing is so clear that I hope that I someday get near his level. I tell the engineers in my group that we write so that we cannot be misunderstood.
I do have one documentation horror story that I want to relate. I used to work as a proposal manager on large defense contracts. I had a former physics professor (PhD from a very well known institution) who worked on some of my proposals as a technical contributor. I could not read a thing that man wrote! I even brought in a very good writing consultant to work with him and that did not help at all. Finally I sat down with him and told him that his writing was terrible and he was going to need to do something else. He demanded to know exactly what was wrong with his writing and I told him that no customer could understand what he was writing. He then told me that he viewed his writing as a form of filter -- any customer that could not understand what he wrote should not be reviewing this proposal.
I then tried to explain to this very intelligent man what the life of a government proposal reviewer was like. I decided to present this poor writer with the following proposal review scenario:
- your proposal is the 20th one the reviewer has seen this week,
- most of the proposals have been a struggle to get through,
- Friday at 4:00PM is the first time he starts reading your proposal,
- your proposal is difficult to read
- the reviewer decides to give your work a low score and go home for the weekend,
- all of our work has been for nothing.
After some moaning and groaning, he got the point. You write for audience and you do not create unnecessary obstacles.