Justify the point that technical documents should not be generated on temporary issues or subjects
Main Body Show
In this Chapter
3.1 Voice and tone
3.2 Mechanics and grammar
3.3 Citations and citation styles
A technical communications writing style is (almost always) concise, precise, direct, and well organized. The following sections outline useful tips and best practices, but know that these are only a starting point. Writing style is something you must be aware of and continually work to refine as you develop your communication skills. A technical communications writing style prioritizes the efficient transfer of information—this may be a change from the types of writing you have done in the past. “High school writing” is more typically descriptive expository essays with a length requirement. Technical communication asks you to document information and communicate it in a concise, precise, and professional way. The focus tends to be more on how well the writing achieves that goal rather than on proving that you read or understand something. Writing assignments often provide specific structures or lists of required elements; however, simply fulfilling these guidelines is rarely enough to create a cohesive, clear document. To be a successful writer not just in first year engineering, but in your major courses and career, you must be attentive to the ways your writing style needs to vary from one situation to the next. Understanding “Writing Style”To understand what “writing style” is, think about all the different ways people talk. With their tone of voice, volume, and speed of delivery, they are able to project different moods, personalities, and purposes. Think about how a person sounds while they’re telling a funny story. Then think about how a person sounds while telling you about their problems. You might also intuitively know that certain ways of speaking are appropriate for some situations, but not for others. If you wanted to deliver a passionate speech to persuade your audience to vote for you, you certainly wouldn’t want to sound like you were delivering a eulogy at a funeral (or vice versa). Those same concepts apply to your writing. How you deliver information—the voice, tone, mood of your writing—is the “style.” It affects how well your audience will understand and respond to the information you are trying to communicate. Since writing style affects how your reader responds, be aware of and use it to help you achieve your purpose. In most situations, you must also communicate in the style your reader expects. This is often driven by genre (type of document) and context. If you are asked to produce a lab report, your reader will have certain expectations about what goes in it, and if you don’t meet those expectations, it will reflect poorly on you as a communicator and make it less likely that your message is delivered. Since writing style affects how your reader responds, be aware of and use it to help you achieve your purpose. Audience and purpose, then, will always affect your writing style, as discussed in Understanding Your Audience. In this chapter, you will find guidance for developing a general technical communications writing style for documents common to First Year Engineering. ConciseSentences should be clear and simple, communicating one concept per sentence. In situations where you want your message to be unambiguous, simple, short, direct sentences are best. Avoid “filler” or “fluff” that clutters up your writing and does not provide useful information. Here are some common types of “filler” to be aware of:
Examples of editing for concision
Keep in mind, however, that shorter is not always better. For example, there may be times when you might sacrifice concision for the sake of sounding more personable, friendly or conversational. If you have to deliver bad news, a two-sentence email might come across as rude or uncaring, while writing a longer email that builds rapport and includes more qualitative, personable touches might soften the blow. This approach could have a positive impact on a team dynamic or a client relationship so that, even with a slightly higher word count, the final outcome is better. Practice & Application: Exercise D – Software Design Pitch Video Prep PrecisePrecise wording avoids ambiguity and ensures the correct information is conveyed to your reader. This is obviously essential to engineering settings, where highly technical information is being communicated. Precise writing will generally meet the following criteria:
Application: Addressing error in lab documentationIn lab documentation, systematic and random error should be addressed. The report should address both the potential errors that could have occurred and the effect those errors would have on the results. Systematic error is an error that cannot be lessened through continued trials. These errors often occur when tools are not sufficiently accurate or a model is used that does not fully explain the system being studied. Address inaccurate simplifying assumptions made in the experimental design or analysis. For example, many experiments assume that there are no frictional losses in a system. This may significantly impact the results of an experiment testing the performance of a motor. Results should acknowledge that additional losses due to friction were not considered. Random errors are unpredictable factors that affect the data gathered from the experiment. The effects of random errors can be minimized through repeated trials. For example, if a beaker should be filled to exactly 20ml, it is approximately equally likely that the researcher would fill the beaker slightly above or below that level. After multiple trials, the average level should be close to 20ml. If it is not, there are likely systematic errors also affecting the experiment. Practice & Application: Exercise E – Making Data Meaningful DirectTechnical communication should get to the point quickly—readers need to know right away what to expect and if the document will meet their needs. A key aspect of directness in writing style is vocabulary. The most direct approach will use vocabulary that is right for the situation and doesn’t use “fancy” or “flowery” words in an attempt to sound “smart” or impressive. It is tempting to write unnecessarily complex sentences in an attempt to elevate the perception of your expertise, but this can obscure the message being communicated… Wait, let’s try that again… Writing unnecessarily complex sentences is tempting when you are trying to seem smart, but this can make your message less clear. Better! In most professional communications, the goal is to sound knowledgeable, yet unpretentious and natural for the situation and audience. Use jargon only if it improves the quality of the communication. See Understanding Your Audience for a discussion of appropriate levels of technicality based on audience type. Some examples of “flowery” language (and more direct replacements):
Here are some additional practical ways to ensure directness in technical and professional writing:
This is important for communicators in many contexts, and the policy of Plain Language is a useful example of a real-world application of “directness” in communication. Plain Language as an example of “Direct” communicationIn 2010, the U.S. Congress passed the Plain Writing Act, which established that government documents issued to the public must be written clearly. Guidelines for plain language have been developed around the world to enhance the public’s access to information. The U.S. guidelines state that users should be able to find what they need, understand what they find, and use what they find to meet their needs. Plain language is a method of communicating information that focuses on the reader’s experience. How can the information be presented in a way that is useful to the reader? Different types of communication will require different levels of background information, but the important information should always be easy to access. Well OrganizedThe order in which information is presented affects how easily it will be understood. As a communicator, you will need to make sure that any document, email, or presentation you create has an intentional, logical, and consistent organization. To be successful as a communicator, you must first understand the organization of the communication and then project that to your audience. Having a “big picture view” of the document’s purpose and structure early in the writing process is key—it is difficult to impose good organization on a piece of writing unless you have carefully considered organization from the start. Here are some practical ways to make a document clearly well organized:
There are several models that technical communications often follow to present information.
While your reader should be able to find specific information easily, they should also see a clear direction for your document as a whole. Consider your reader’s experience empathetically. If you were reading this document, where would you expect to find certain information? Will your reader gain a clear understanding of your process from reading the document from start to finish? A Note About Lab Report OrganizationA Lab Report contains sections for Results and Discussion. Students often present the data from a specific portion of the lab, then immediately discuss the meaning of that data within the Results section before moving on to the results of the next portion. From a chronological perspective that seems logical, but that is not the structure of a lab report. Switching back and forth from results to interpretation is awkward and may leave your reader looking for data interpretation in the Discussion section that is not there. See Lab Report Content Guide for more information. Practice & Application: Exercise F – Precision and Paragraph Organization Key Takeaways
Additional ResourcesThe Basics of Scientific Writing (University of Nebraska) What should be avoided in a technical document?Let's look at some of the most important things to avoid when writing technical documents.. 1) Vague Language. ... . 2) The Passive Voice. ... . 3) Unnecessary Information. ... . 4) The Future Tense. ... . 5) Disorganization. ... . 6) Complex Sentences. ... . 7) Not Using Diagrams.. What are three challenges to consider when producing documents for technical communication?Audience, purpose, and document related factors.
What are the ethical considerations in writing technical papers?4.5 Ethical Issues in Technical Writing. Research that Does Not Support Project Idea. ... . Suppressing Relevant Information. ... . Limited Source Information in Research. ... . Presenting Visual Information Ethically. ... . Additional Concerns.. What is the main purpose of creating technical documentation?Technical documentation is created for the sole purpose of making it simple for the end-user to understand the work dynamics and architecture of a product or technology they use.
|