What makes Technical Documents Great - Lesson 1

Writing Great Technical Documents : By Janet S. Underwood Lesson 1 What Makes Technical Documents Great? Writing Great Technical Documents Copyright © 2009-2010 by Janet S. Underwood. All rights reserved. No part of this course may be reproduced, stored, saved , or distributed without written permission of the author.

What Makes Technical Documents Great? : What Makes Technical Documents Great? Welcome to Writing Great Technical Documents! My name is Janet Underwood and I’ll be your instructor for this course. I’ve been a professional writer for more than 20 years. During that time, I’ve worked in publishing, business, and nonprofits. I’ve been a reporter, an editor, a technical writer, and an instructor. Before my professional writing career, I was an English teacher. In the early 1990s, I started my own business. Through it, I’ve written technical documentation and training courses for telecommunications, financial, software development, computer, medical, and public utilities companies. I’ve also been a consultant on training programs for government agencies such as NASA, the Department of the Army, and the Department of the Navy. For the past eight years, I’ve developed and taught courses that have been offered through colleges and universities around the world.

Slide 3 : In business, good writing skills are as important as technical expertise. As our world becomes increasingly complex, people who can write clearly and powerfully about technical subjects are valued in business, industry, and government. If you can explain your ideas in compelling ways, if you know how to write in a manner that engages people and inspires them to act, you are writing documents that get results. Every working day, thousands of scientists, engineers, programmers, business analysts, technical writers, managers, and others write technical documents. They write these documents hoping that their readers will understand what they’ve written and do certain things as a result of reading their work. Unfortunately, many of these documents fail to achieve their purposes. Sometimes the style of writing turns off readers. Sometimes the writers use words their readers don’t understand. Sometimes the organization of the document is confusing for readers. The number one reason why technical documents fail, however, is that we often believe that what we have to say is more important than how we say it.

Slide 4 : Unfortunately, that isn’t true. You can have the best idea in the world, but if you don’t communicate it in a way that your readers can understand, your idea won’t be heard. To communicate successfully, we have to consider how readers will receive our information and whether they’ll understand the words we use. We have to write about complex subjects in a way that enables others to understand what we’re writing about and compels them to act upon our words, whether they’re using our documents to learn how to use a new computer system or to approve funding for a research project. Fortunately, you can learn how to do these things. By taking this course, you’re taking the first step to learning how to write technical documents that help you achieve your goals and more clearly explain your ideas to others. In this course, we’ll discuss how to write for different audiences and how to write with a more polished style. We’ll look at different styles of technical writing and scrutinize the elements that make your writing more powerful, clear, and organized. We’ll also discuss how to incorporate graphical elements into your documentation to make it more interesting and informative.

What You’ll Learn… : What You’ll Learn… In this lesson, we’ll talk about introductory concepts, such as how we can use language to separate ourselves from others. We also discuss the benefits of putting in the extra effort to make your writing stand out. Finally, we talk about the way we think about technical documentation and some essentials of great technical documents. Let's get started.

Our words define us : Our words define us The way we communicate tells others a lot about us—how educated we are, how much we know, where we came from, and even what kind of work we do. From ancient times, words have identified people as being a part of certain communities. The English language originally evolved from the language of West Germanic invaders called Angles, Saxons, and Jutes. These tribes populated the British Isles in the fifth and sixth centuries A.D and spoke a language called Old English. Old English was a simple language with many one-syllable words and a limited vocabulary. Since the Angles, Saxons, and Jutes didn't have words for everything they encountered in their new home, they borrowed some Celtic words from the original inhabitants of the British Isles. Over the years, they borrowed more words, and dialects emerged, but Old English remained essentially the same for hundreds of years.

Slide 7 : All this changed shortly after 1066 A.D., when William the Conqueror conquered England and the Anglo-Saxons in the Battle of Hastings. He brought with him a new language, Anglo-Norman. This French dialect had Germanic influences and Latin roots. The conquerors added a large number of Anglo-Norman French words to the English language. They used these words to set themselves apart from the people they had conquered and to distinguish their social class. The Norman aristocracy preferred to use the supposedly more genteel Anglo-Norman words, while Anglo-Saxon commoners used Old English words. For example, the Norman aristocracy called cooked meat beef, while the Anglo-Saxons used the Germanic word cow. Since the Normans ruled the courts and the government, many legal and political terms they used had Anglo-Norman roots, a legacy that is still with us even today.

Slide 8 : From 1348 to 1350, the Black Death killed one-third to one-half of the English population. After the plague had run its course, the working and merchant classes became more economically and socially important. During this time, the so-called commoners began to use more of the Anglo-Norman words, and the aristocracy began to use more of the Old English words. The language that evolved was Middle English. The most famous example of this is Chaucer's Canterbury Tales. Unlike Old English, modern English-speaking people can read Middle English (with difficulty). As Europe emerged from the economic stagnation of the Middle Ages, the Renaissance dramatically changed the language again. There was a new emphasis on artistic, social, scientific, and political thought. For the first time, people could improve their status through education and ideas. Classical works became popular, so scholars began translating classical works into English. Since many words in the Greek and Latin texts didn’t have English equivalents, they borrowed certain Greek or Latin words, thereby adding more words to the language. In some cases, they "Englished" the Greek or Latin words to form new words. In doing this, the scholars were following a common tradition of borrowing words from other languages out of necessity. Historiated initial 'C' containing a scene showing monks, disfigured by the plague, being blessed by a priest. Title of Work: Omne Bonum Author: Palmer, James le Production: England (London); 1360-1375 Language: Australian From The British Library; Record Number: c6541-07; Shelfmark: Royal 6 E. VI; Page Folio Number: f.301. This image (or other media file) is in the public domain because its copyright has expired.

Slide 9 : During this time, people started using words from other languages again to show their superiority to others. Moreover, they didn't always just borrow words. As Latin and Greek words were being added to the English language, people who wanted to sound more educated than they really were or who wanted to elevate their social status began to sprinkle their writings and speech with words that sounded as though they were Latin or Greek, but which actually were made up by the writer or speaker. Educated people called these words inkhorn terms, a term of derision used to indicate that people who used these words pulled them from the containers in which they stored their ink. Interestingly, many inkhorn terms survived. We use many of them today, including words such as the following:

Slide 10 : Through the years, the industrial and scientific revolutions brought the need for even more new words. Writers often turned again to Latin and Greek for words that would describe new creations and discoveries, adding words such as oxygen, protein, and vaccine to the language. Some fields, such as medicine and science, have long relied upon Latin and Greek words or words with Latin and Greek roots. Those educated in these disciplines have no problem understanding these words. To outsiders, though, it often sounds like, well, Greek (or Latin). Every profession has its specialized language that people outside of that community may not understand. English is a marvelously adaptive and flexible language that allows us to create words to describe new concepts or borrow words from other languages to create a more precise vocabulary.

Slide 11 : There’s nothing wrong with creating new words as needed or borrowing words from other languages. This is a natural part of the evolution of our language. The problem occurs, however, when we fail to explain those words, when we consciously or unconsciously use our words to set ourselves apart as the Norman aristocracy tried to do. Even worse, when we use words that others don’t understand, our readers may think that our writing is pretentious and affected. They may think that we’re trying only to impress others, like those people who made up inkhorn terms. In the process, our words may create not bridges to our knowledge and ideas. but barriers to communication with others. Does Your Writing Create Bridges or Barriers?

The Benefits and Risks of Our Words : The Benefits and Risks of Our Words Every technical writer can cite examples of subject-matter experts who know their subjects so well, they can’t explain them to others. The words they use in their respective disciplines are so common to them, they’ve forgotten how to translate them into simpler terms. It doesn’t occur to them that others don’t have the same vocabulary that they have. Although they may not mean to do so, by using these words, they’re effectively setting themselves apart from the "common" person, which may include anyone who isn’t a part of their professional community.

Slide 13 : In addition, it’s easy to fall into certain patterns of writing that make it difficult to communicate with others. Many professional communities have their own unwritten conventions of the proper way to communicate. When first starting their careers, professionals must learn the writing style that their colleagues think is acceptable. In many disciplines, writers learn that they shouldn’t write with too much enthusiasm or assertiveness. They learn to use a writing style that isn’t straightforward and to suggest when they really mean to tell. Again, there’s nothing wrong with using a writing style that your professional community thinks is best. To write better technical documents, however, we must understand when it’s appropriate to use the language and political sensitivities of our peer groups in our writing and when we need to write in a different style. When writing for our peer groups and others, we need to know how to structure our documents so they’re compelling and communicative. When we’re writing for others, we need to understand how to communicate our ideas in a compelling way to those groups as well.

Why It’s Essential to Write Better Technical Documents : Why It’s Essential to Write Better Technical Documents Today, workplaces are complex and rely heavily upon communication. An office in Cincinnati, Ohio, may need to send detailed instructions for installing a new generator to an office in the Philippines. An engineering team may be made up of people with offices in the United Kingdom, Asia, and France. Scientists may have to present their findings to people outside of their profession. With the increased need to communicate complex ideas to diverse communities, the ability to write well can make or break your career. Well-written documents demonstrate your ability to synthesize and clarify complex subjects. The ability to write compelling, clear documents can help you advance in your career and help your company make better decisions and make more money. Well-written documents can even save lives.

A Case Study’s Chilling Conclusions : A Case Study’s Chilling Conclusions In his book Technical Writing Style, Dan Jones includes several case studies of how failures in communication may have contributed to disasters. One case study examines the communication failures associated with the Space Shuttle Challenger tragedy in 1986. The study is chilling to read. One major reason for the accident stands out--—two professional communities failed to communicate. According to Jones, it happened like this: Six months before the fateful day, engineers documented problems with the SRB o-rings used on the Challenger. They sent memos about the field joint problems to management and NASA officials. They clearly told them that if the temperature fell below the mid-50s (F), the o-rings could fail. Management ignored the engineers' warnings and approved liftoff for a cold January morning. The temperature was in the 30s (F). Seventy-three seconds after lift-off, the o-rings failed, and seven people died.

Slide 16 : The presidential commission that investigated the tragedy concluded that the temperature had been the primary cause of the catastrophe, and that "Communication during the launch decision process was inadequate." Key individuals' objections to the launch were not registered to the top program officials, the commission said. The key individuals who had objected to the launch were the engineers. Why didn't anyone take their warnings seriously? After analyzing the writing style of their memos, Jones concludes that there was a communication failure between the engineers and management. The engineers used clear, concise language, but their writing styles did not compel the management group to act. The engineers did not meet the needs of their readers.

Slide 17 : This tragic story reminds us that our technical documents must speak to their readers. They must use language that encourages readers to respond to their message. They must engage their readers in the subject and persuade them to see the writer's viewpoint. Great technical documents broaden the horizons of their readers. They empower people with knowledge and inspire them to explore more options. By writing in a manner that shares your vision and knowledge with others, you are helping them to build bridges to new knowledge and a new vision within their own minds. The ability to write great technical documents is a win-win situation. You will benefit and most likely advance in your career. The people who read your documents will understand the concepts you present more quickly and take them more seriously.

What We Expect from Technical Documents : What We Expect from Technical Documents When you ask people what they expect when they read technical documents, many will probably tell you that they expect them to be: Difficult to read Boring Uncreative Formal.

The Traditional View : The Traditional View In part, these expectations stem from the traditional view of technical writing that technical documents should always be objective, impersonal, neutral, and functional. The writing style should be transparent, meaning that the writer is invisible to the reader. Additionally, the traditional view is that technical writing should devoid of any embellishments or attempts to persuade the reader to adopt a certain viewpoint. To write these kinds of documents, writers must become rather like information machines, impartially passing along technical information without imprinting it with their personalities or ever interpreting information creatively. This view of writing technical documents grew from the technical world, where professionalism is equated with objectivity and logic. Writers cannot express any passion for their subjects. They must take pains to avoid persuading their readers—often so much so that their readers are not certain what they were trying to say. Unfortunately, this type of writing has produced many incomprehensible technical documents.

Slide 20 : In an attempt to be objective, writers using this style overuse qualifiers. They eliminate actors in their sentences in an attempt to maintain an impersonal tone to their writing. They purposely use a flat style of writing, taking care to eliminate any words that could be interpreted even remotely as emotional or expressive. Here’s an example of this type of writing: Prior authorization has not been granted for the distribution of information other than that which has been proposed or implied by reference in this proposal. If such information is distributed or subsequent representation that permission to distribute this information has been granted, authorization is not to be assumed. What’s really being said? One version might be this: We give permission to distribute only the information that is included in this proposal. We have not authorized anyone to provide you with different information.

The New View : The New View In the 1970s, a new view of technical writing emerged, due in part to President Jimmy Carter issuing Executive Order 12044, which mandated that federal regulations be "as simple and clear as possible, written in plain English, and understandable to those who must comply with [them].“ Although this order was rescinded by later administrations, The idea caught on. People started realizing that technical documents can be creative and dynamic. They can express points of view. Most importantly, people recognized that many, if not all, technical documents are written to persuade others.

Slide 22 : While this may seem like heresy, we need to stop and ask ourselves some questions. Are we being less professional when we write to persuade others to think about a subject in a certain way? Are we abandoning scientific, logical thinking if we speak more directly to our readers? Think about this. When you write a document explaining how to use new software, what are you doing? You’re writing to persuade others to perform tasks in a certain way. When you write a report about an engineering problem that you’ve discovered, what are you doing? You’re writing to persuade others to take the problem seriously enough to act. The new view of technical writing recognizes that the purpose of technical writing is to inform, to be functional (in that it provides useful information), and to meet the needs of a specific audience.

Slide 23 : It also recognizes that technical writing relies upon certain sentence types that promote clarity (for example, subject-verb-direct object constructions) and structured paragraph patterns (such as general to specific) more commonly than other types of writing. Most of all, this view recognizes that technical writing is about sharing ideas and thoughts with others. To convey those ideas and thoughts, writers must be creative. They must present information so it’ll have the most impact upon its readers. Daniel Marder, author of The Craft of Technical Writing and other books, wrote the following in an article for the Society for Technical Communications' magazine, Technical Communication: “We fail to realize that in technical reporting, only the subject is technical. Despite all the razzle-dazzle in our most technical of technological times, the substance of technical reporting remains a formal discipline of the mind, a rhetorical discovery of the best ways and means to persuade an audience.”

How do you write well and persuasively? : How do you write well and persuasively? We’ll discuss this throughout the course, but you can take these steps right now. Write clearly.If people don’t understand the words that you use, they can’t be persuaded by your ideas. Write to express, not to impress.If you’re writing for your peer group, use words that are familiar to them. If you’re writing for management or a group that may not know these words, use other words or explain your terms to them in simple words. Use concrete words instead of abstract ones.Using an abstract word such as device when you are referring, for example, to a network router can lead to misunderstandings and confusion for your readers. The word many leaves the interpretation up to our readers, whereas saying 500 gives them a number they can envision.

More Ways to Write Well and Persuasively : More Ways to Write Well and Persuasively Avoid jargon.Jargon is the specialized vocabulary of those in a specific field. If you write, He went online and uploaded the JPEGs to the host for the company's Web site, you are using jargon. If your readers are not familiar with this terminology, rephrase it along these lines: He connected to the Internet to transfer graphics files to the computer where the company's Web site is located. Avoid slang words and phrases.Words such as game plan, bottom line, and bean counter have no place in business documents. Slang words and phrases are nonstandard usages composed of arbitrarily changed words and forced or facetious figures of speech. Since many companies have international offices, it is important to avoid using slang terms that people in other cultures may misunderstand.

Yet More Ways to Write Well and Persuasively : Yet More Ways to Write Well and Persuasively Avoid gobbledygook.Gobbledygook is unintelligible, pretentious language that some writers unfortunately think makes their documents sound more official. Gobbledygook is a sentence such as At this juncture, it would be prudent to implement the deployment of the vertical antipersonnel device, which means in plain English, We should drop the bomb now. Use active voice whenever possible.The subjects of your sentences should perform the actions stated by the verbs. When you use passive voice, your readers do not know who the actor is until late in the sentence and maybe not even then. The following sentence uses the active voice: The senior officer conducted an analysis of the new test facilities. Here's the same sentence in passive voice: An analysis of the new test facilities was conducted by the senior officer.

Slide 27 : We’ll talk more about these and other ways to improve your writing in other lessons. If you choose to work on just one of these things, however, you’ll notice an immediate difference in your writing. Your writing will have more energy, and your readers will be more interested in what you have to say.

Summary : Summary Writing technical documents requires discipline and skill, but it has more in common with all types of writing than many people realize. As with all types of writing, a fundamental purpose of a technical document is to persuade others to do something or think something. While we may be tempted to use the language and conventions of our professional community when writing all of our technical documents, we need to consider who our readers are and adopt a style that will have the most impact upon them. We need to write our documents in a manner that builds bridges of communication and successfully informs our readers. We must resist the temptation to use the language in ways that build barriers to communication and set ourselves apart as a community, if our ideas and concepts are to reach their true potential.

Slide 29 : The ability to write effective technical documents has many benefits:

Slide 30 : We learned that while most people think technical documents must be boring and difficult to read, there is a new view of technical writing. While technical documents should always be functional, they do not have to be boring. You may state your point of view. You may show your enthusiasm when appropriate. If needed and appropriate, you may use creativity and persuasion to make your documents have the greatest effect upon your readers. While you must do many things to write great technical documents, we talked in this lesson about the following: Clarity Concrete words Jargon Slang Gobbledygook Use of the active voice Start now by focusing on just one of these in your writing. Set a goal to write more clearly or to use words that are more concrete. Be aware of the jargon you may be using, especially if people outside of your professional community will read your documents. Work to eliminate slang and gobbledygook in your writing. Write more sentences in the active voice. By doing just one of these things, you will be rewarded with an improvement in your writing.