Communicating Bad

Member Submitted

Companies place little emphasis on the quality of an engineer's writing. An engineer's writing is usually only for evidence a particular transaction took place, or for proof he did the appropriate research. There is hardly ever any emphasis on the readability or usefulness of the writing. In this article, the author states several reasons for this problem and that development teams must come to understand in order to find a solution.

It is amazing what little emphasize companies place on communication, particularly writing. Often times a manager will say "Put it in writing," "Can you type up a document explaining it," etcetera. All the manager is asking, is for evidence a particular transaction took place, or proof an employee did the appropriate research. There is hardly ever any emphasis on the specific content and readability of the writing. Is there any value in writing a document if you do not write it well? Absolutely not. There is no value in a poorly written document.

Before me now is a document explaining some technical details of a system in my company. Had I not known the author, I would say their first language is not English. However, this is not the case at all. Why then, did the author write the document so poorly? I offer a few reasons.

First, the author does not know the purpose, or audience, of the document. When a manager says, "Can you type up a document explaining our system," the manager is not clear on the intent of the document. The assumption by the author is, only he will use the document. No matter how the author writes the document, he will most likely understand his own writing. Therefore, the author determines it is not important how he writes the document. To prevent this from occurring, the manager must clearly point out the intent, and the audience, of the document

"Can you type up a document explaining our system to the VP of IT so she can come to a conclusion on whether we should use the same system the California office is using? The document would be completely different if the question were, "Can you type up a document explaining our system to the Chief Architect so he can integrate the e-mail application with our system?"

The second reason for poorly written documents is, the author does not understand the importance of clear communication in the document. Too often, especially when the author has full access to the audience, the author will assume she can clarify information by “following up” with the audience. A "follow up" is a good way for an author to determine what is lacking in her paper, and revise her document accordingly. A "follow up," however, is not a means for supplementing a document. A document must be a complete entity alone. A document's purpose is usually to ensure the author, and others, do not have to waste time answering the same questions repeatedly.

People often use the excuse, "It is too complicated to explain in writing." This is exactly the reason why someone should sit down and take the time to explain it properly in writing. Writing allows the author to organize her thoughts. This organization may even help the author solve a problem or get new ideas. Furthermore, writing is not limited to words. Diagrams and pictures are acceptable in most writings. The writer must keep in mind, however, a diagram is useless without proper explanation.

Finally, are the people writing the documents really the right people for the job? Generally, the author does not know how to ensure he is communicating clearly. Nearly everybody in the workplace writes memos, e-mails, papers, and etcetera. However, not all of these people are writers. Asking an engineer to write a document, is nearly the equivalent of asking a writer to design a word processor. How does an engineer know he is writing the document properly? How does the writer know she is designing the word processor correctly? They do not know. They are two fundamentally different skills. The simple solution is to have the writer critique the engineer's document. The common excuse here is, "The writer does not understand the system." However, this is exactly the reason the writer should review the document. The writer is concerned about the quality of the writing, and the content will not distract the writer like it would an engineer.

The document in front of me has a paragraph with one, 35 word sentence. The paragraph should be two, 10 word sentences. The run-on, 35 word, sentence is an example of an unorganized thought. My guess is, the author decided, more words in less time would make her look good. We have all fallen into this trap, starting in elementary school. The author knows what she means, and has 35 words to prove it. I ask managers, and engineers, to take the time and let everyone understand your document, not just the authors.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.