Technical Writing Fundamentals Presented by Elizabeth Hardin University of Alabama in Huntsville This webinar will cover ● ● ● ● ● ● ● Introduction: What is technical writing? Key Concepts: Understanding your audience and purpose Planning and organizing your document Drafting your document Using plain language Revising and editing your document Reviewing grammar and punctuation When you have questions ● Between each section of this presentation, I will answer relevant questions. ● There will also be time at the end of this presentation for questions. What is technical writing? ● Technical writing, or technical communication, is the use of words and images to explain complex concepts in ways that people can understand. ● It can be written (like a software user manual) or presented (like a video tutorial that demonstrates a process). ● It relies on words and images to help an audience understand a technical concept or complete a task. ● Every document has its own audience (who will read it?) and purpose (why will they read it?). Key Concepts: Audience and Purpose Audience Audience means the people who are reading and using your document. ● Analyze your audience ○ While the audience for your academic writing so far has probably been your instructor, ○ the audience for documents technical writing is different and varied. Understand the audience’s needs and expectations. Audience Consider primary and secondary audiences ● If audiences other than your primary one will read your document, consider ways to make it appropriate for multiple audiences. ● Make your document modular (break it up into components for multiple audiences). ● Examples: “admin” and “general user” sections or including an executive summary for people who don’t need the technical details. Audience ● Your responsibility is to help the reader understand the information easily. ● The content is technical and complex; it’s our job to communicate it effectively, without the audience having to do extra mental work. ● If they’re thinking too hard about how you’ve presented your information or what you mean, they’re not thinking about the content. Purpose ● No one wants to read what you write. They must read it to do their jobs. ● What is the audience going to DO with your document? ● What do you want the audience to do with this information? For example, ● Are they trying to get enough information about your project so they can approve it? ● Do they need help assembling a table from IKEA? Purpose Most of the writing technical writers do falls into two categories: 1. To help others learn about a subject, carry out a task, or make a decision. ● If you’re writing a proposal, your document’s purpose is to help the reader make their decision about who to hire or what project to fund (hopefully yours!) ● If you’re writing software user help, your document’s purpose is to help someone achieve a goal with the software. Purpose 2. To encourage others to take action. ● An electric car company might describe their vehicles’ specifications and benefits to encourage customers to buy their product. Genre ● Genre means the type of document you create. ● The genre dictates the document’s structure and delivery. ● Examples: ○ Technical report ○ Blog post ○ Memo The Writing Process: Planning, Drafting, Editing, Revising, and Proofreading Planning The planning process ● ● ● ● Analyze your audience and purpose Generate ideas Research Organize and outline your document Planning ● Determine the structure and content of your document. ● Some of the structure and content is determined by genre. Planning For this challenge, your audience and purpose of your documents are set for you. You are writing two reports (and presentations) that have specific requirements laid out in the program guidebook. ● Design Review ● Operational Readiness Review Planning ● Design Review ○ Audience: management or customers ○ Purpose: to prove to management or customers that your team has considered all factors and reasonable design options and that your design meets all requirements for the project ● Operational Readiness Review ○ Audience: management or customers ○ Purpose: to prove to management or customers that your product is ready to complete the mission. Planning: Methods of development Problem -> Method -> Solution ● Describing the problem to be solved and then your approach to solving it This is the most common organization for technical reports and design reports, and the one you’ll use as you report your team’s solutions to the challenge. Planning: Methods of development Choosing a method of development helps you organize and present your information in a logical way. For example, some methods are ● Chronological (describing something in the order it happened or will happen) ● Spatial (describing the physical structure of something) ● General to specific (explaining a broader idea or context and then focusing on a specific, complex idea) ● Problem -> Method -> Solution (describing the problem to be solved and then your approach to solving it) Planning: Document organization The major sections of the reports are provided for you, as described in the HERC Guidebook. For example, for the Design Review Report, you must include ● ● ● ● ● ● Cover Page Vehicle Criteria Task and Other Mission Components Mission Performance Predictions Safety Project Plan You can start outlining your draft with these major sections as headings. Planning: Document organization Executive summary ● Most formal reports include this section, which is an overview that provides the reader with the report’s main points and results. ● It should be standalone, meaning that a reader who doesn’t need to know the details can understand the major points of the report. ● It’s similar to an abstract. Planning: Document organization Executive summary ● For a 10-page report, between 100-150 words should be enough. ● Include it in the report after the cover page, and label it (use a section header like “Abstract” or “Executive Summary”). ● Write it last. Questions? Drafting Drafting ● Once you know your major topics and have an outline, start writing. ● Start with the easy stuff. Make notes about what to fill in. ● Drafts are fluid, not written in stone. Be flexible and willing to adapt and change when you can. Document Design Drafting: Working with style guides and templates Many elements of your reports’ style are dictated by the HERC guidebook. ● For example: “The Design Review and Operational Readiness Review reports shall be in Arial, size 12 font on 8.5 x 11 paper with 1 inch margins. ● Each report shall include the team name and report title on the cover page. All pages shall be numbered. ● Reports shall not exceed the page limit. Any additional pages will not be scored.” Drafting: Document and page design tips ● Organize your report with section headings and subheadings. ● These document design features help the audience understand how your ideas are organized. ● Keep fonts and font sizes consistent. ○ Unless directed otherwise, if your body text is size 12 pt., 14 pt. bold font is good for ○ headings. Subheadings can be 12 pt. ALL CAPS. Caption figures and title tables with 11 pt. font. Drafting: Document and page design tips ● Use single or 1.15 spacing. ● Don’t indent first lines of paragraphs. ● Use a line break (a blank line) between paragraphs and before and after headers. ● If a section heading can fit on the bottom of a page, but its content can’t, start the section on a new page. Drafting: Visuals ● For your reports for this project, you will include your graphics in an appendix. ● Make sure to give all graphics a title or caption so you can refer to them in the text. ● Title tables above the table (Table 1: Costs of materials). ● Caption figures below the image (Figure 1: Wheel design). ○ Tables and figures are numbered independently. You can have both Table 1 and Figure 1 in your report. ● Use these titles and captions to refer to the visuals in the text. ○ As shown in Figure 1… ○ Table 1 shows… Tone and Word Choice Tone and word choice Formal vs. informal ● Documents like reports are usually formal, but don’t let “formal” mean “overly complex.” Use plain language and straightforward construction (more about that soon). ● More formal writing may require you to use passive construction (more about that next) and third person (no “I” or “we”). Tone and word choice Passive vs. active construction ● Passive: The temperature of the environment was considered. ● Active: Our team considered the temperature of the environment. Formal reports often use passive construction. This emphasizes the work that was done or the findings of a test instead of who did the work. Tone and word choice Verb tenses: consider the document’s purpose. Keep it consistent. Use future tense for planning documents and proposals. ● The vehicle will be tested for stability. Use past tense for reports about things that have been done (test reports, for example). ● The vehicle was tested for stability. Precise language ● When you describe something, use precise, verifiable language. ○ Instead of “multiple holes were drilled in the plank,” write “three 1” holes, 2’ apart, were drilled into the plank.” ● Avoid subjective statements. When evaluating something, include quantifiers or include the criterion you used to evaluate. ○ Instead of “this design was best,” write “this design completed the test successfully and was 2 pounds lighter than the other options.” Paragraphs ● One paragraph = one idea. ● Use clear topic sentences to alert your reader to what the paragraph is about. ● Use transition words and phrases (however, next, then, as a result...) to help the reader understand connections between paragraphs. ● Avoid very long paragraphs. ○ There’s no rule about exactly how long a paragraph should be. If you notice paragraphs that are ½ a page to one page long, read them carefully to figure out where you’re transitioning to a new idea and break the paragraph in logical places. Using Plain Language Plain Language and Clarity A goal of professional communication is to be clear and precise so readers can easily understand the message. Plain Language ● It’s the law. ● It’s an ethical issue. ● The Plain Writing Act of 2010 requires all organizations to make sure their writing helps readers ○ Find what they need ○ Understand what they find ○ Use what they find to meet their needs ● Government guidelines here. Plain Language Watch out for jargon ● Every field has its specialized language. ● If the audience (the reader or user) speaks the same “language,” it’s ok to use it. ● But remember that you’re writing for the user. If they aren’t likely to know a technical term, use a word they know. Plain Language ● Acronyms—spell them out the first time you use them. ● Example: ○ First time: Computer-based training (CBT). ○ Subsequent times: CBT ● Note: Keep punctuation consistent (choose either C.B.T. or CBT). Plain Language Watch out for redundant words ● Absolutely complete ● Refer back ● End result ● Final outcome ● Reduce down Common wordy phrases and their concise equivalents In the event that if Until such time as when Have the capability of can At this point in time now Due to the fact that because With reference to about Prior to the start of before Plain Language Watch out for “hidden” verbs or unnecessary nominalization. “Apply for the program” is clearer than “Make an application for the program.” “The officer investigated the claim” is clearer than “The officer performed an investigation on the claim.” Plain Language Tip: Read your writing out loud. If it sounds wordy or awkwardly phrased, it’s also wordy and awkward in writing. Plain Language Revision Examples Make this sentence more concise: We remain in communication with our sales staff on a daily basis. Plain Language Revision Examples Make this sentence more concise: We remain in communication with our sales staff on a daily basis. We talk to our sales staff every day. Plain Language Revision Examples Make this sentence more concise: For all intents and purposes, our company’s long-term success depends to a certain degree on various factors that are in general difficult to foresee. Plain Language Revision Examples Make this sentence more concise: For all intents and purposes, our company’s long-term success depends to a certain degree on various factors that are in general difficult to foresee. Our company’s success is uncertain. Questions? Revising Revising ● After you have a draft, revise it. ● Revision = re-vision (seeing again) ● You’re not writing in stone--if something needs to change, change it! Revising ● Go back and read your document carefully to make sure you have communicated what you need to. ● Remind yourself of your audience and purpose. Has your understanding of the subject, audience, or purpose changed? Revising ● If your template or requirements allow you to, you can change the order of sections to ensure that you have a logical flow. ● Write the introduction (or abstract or executive summary) last, when you have the most knowledge of the document. ● The abstract or executive summary needs to follow the same order of the document, so don’t change up your document and then forget to update the abstract. Editing Editing Editing means checking your revised draft to improve your writing. ● ● ● ● Mechanics (use of numbers and abbreviations) Word choice and diction Grammar Punctuation Editing for consistency ● Keep abbreviations consistent (capitalization, punctuation) ● Write terms consistently (don’t write meters in one place and metres in another) Editing for word choice ● Don’t try to vary your writing for interest, like you might do in an academic writing or fiction writing. ● For example, in instructions for computer software, if you use the verb “select” to mean clicking a button, use “select” every time to describe that action. Grammar and Punctuation Review Grammar and Punctuation Review: Common Errors ● ● ● ● ● ● Comma use Other problematic punctuation Fused sentences and comma splices Commonly confused words Proper plurals Parallel structure Commas after introductory elements Include a comma after introductory elements of any length. ● Between 40 and 50 degrees west and just south of 10 degrees north in the western end of the doldrums belt, calms do occur with frequency, and hurricanes originate there with great frequency. ● Today, the computer consortium of IBM, Motorola, and Apple is announcing its new PowerPC chip. Unnecessary commas INCORRECT: The separator between black mix and the zinc electrode, consists of a paper barrier coated with cereal or methyl cellulose. Compound sentences Include a comma after a coordinating conjunction (for, and, nor, but, or, yet, so—use the mnemonic FANBOYS) ● The younger students are computer literate, so we will not teach basic computer skills. Compound predicates This is when the subject is doing two things in the “verb” part of the sentence. No comma needed. ● Inspectors must enter their name in the record book and lock the cabinet. Series elements ● I support the Oxford comma (the comma after the final element in a series). ● There is some debate about it, but using it can reduce confusion and make writing clearer. ● My book includes quotes from my parents, the president and the vice president. ● My book includes quotes from my parents, the president, and the vice president. Semicolons Used to connect two independent clauses (clauses that can stand alone as sentences) not linked by a coordinating conjunction (for, and, nor, but, or, yet, so). ● The older interface was less user friendly; research shows users prefer the updated version. ● The older interface was less user friendly, and research shows users prefer the updated version. Semicolons Use a semicolon when using ”however” to join independent clauses. ● Usability research showed that users over 40 prefer the older UI; however, younger users like the new version. Semicolons Can also be a “supercomma,” to separate items in a series that already contains commas. ● The HOA meeting was attended by three elected officials: James Peterson, HOA president; Michelle North, HOA vice president; and Harry Albert, recording secretary. Apostrophes Used to indicate possession. ● ● ● ● The report’s contents (singular possessive) Charles’s colleague (singular possessive) The documents’ pages (plural possessive) Children’s toys (plural possessive) Apostrophes Don’t be fooled by words that look and sound plural, but aren’t, like lens or license. ● ● ● ● I lost one contact lens. I lost both of my contact lenses. My right contact lens’s prescription seems wrong. My contact lenses’ filthy condition appalled my eye doctor. Apostrophes: Compound possessives Add 's to the end of the last noun to show joint possession of an object ● Ann and Tom’s house ● Amanda, Jill, Alice, and Sejal’s lunch Apostrophes: Compound possessives Add 's to the end of the both nouns to show possession of different objects ● Ann’s and Maggie’s houses Possessive pronouns The pronominal possessives hers, its, theirs, and yours have no apostrophe. ● The house is ours. ● He is a friend of yours. ● The granite countertop has lost its shine. ○ Don’t let spellcheck talk you into the wrong “its” in this case. Apostrophes Not used to create plural nouns. ● INCORRECT: The graphic’s in this application are cutting edge. ● CORRECT: The graphics in this application are cutting edge. Apostrophes Watch out for words that look “weird” when they’re made plural. They might have an unexpected plural form, or they might just be correct with an “s.” ● Vertexs (?) Vertex’s (?) NO! ○ Vertices ● Memo… memos (?) YES! Proper plurals Watch out for words whose plural forms are hard to say. They still need an “s” to make them plural in writing. ● ● ● ● Scientist/scientists Mask/masks Therapist/therapists Motorcyclist/motorcyclists Colons ● Used to introduce a word, phrase, or clause that amplifies, illustrates, or explains a general statement. ○ In our report, we compare three elements of the elevators: speed, safety, and passenger capacity. ● The text preceding the colon should be able to stand alone as a complete sentence, without the list. ○ INCORRECT: In our elevator report, we compare: speed, safety, and passenger capacity. Hyphens Hyphenate compound adjectives when they come before the word they modify (but not when they come after). ● start-up costs ● salt-free crackers ● These crackers are salt free. Hyphens There is no need to hyphenate modifiers constructed from an adverb and an adjective. ● Newly built airport ● Recently acquired evidence Fused sentences, comma splices, and run-on sentences ● Run on sentences are not simply sentences that are too long. ● They contain two or more independent clauses that aren’t connected properly. ● Incorrect connections include ● No connecting punctuation at all ● A comma ● A coordinating adverb (like however, therefore, furthermore…) Fused sentences, comma splices, and run-on sentences ● All of our reports are peer reviewed, our colleagues proofread for grammar and clarity. ● I emailed the report to my boss, however she ignored it. ● Every inspector is expected to file a separate report there are no exceptions. (These are ALL run-on sentences.) Fused sentences, comma splices, and run-on sentences Corrected sentences ● All of our reports are peer reviewed. Our colleagues proofread for grammar and clarity. ● I emailed the report to my boss; however, she ignored it. ● Every inspector is expected to file a separate report, and there are no exceptions. Objective pronouns A pronoun that stands for the person or thing receiving the action of the verb or following a preposition. CORRECT: Mr. Jones hired Robert and me. INCORRECT: Mr. Jones hired Robert and I. Tip: Cross out “Robert and” and see how the sentence sounds. Subjective pronouns A pronoun that is used as the subject of a clause or sentence. CORRECT: Robert and I interviewed for the same position. Subject-verb agreement Even if the subject is far away from the verb, make sure they agree. The documents, which are outdated and ready to be updated by the writing team, are stored on the server. Subject-verb agreement: There is versus there are Use there are when the actual subject is plural. Use there is when the actual subject is singular. ● There are numerous errors in this document. ○ Numerous errors are in this document. ● There is a spelling mistake on page 5. ○ A spelling mistake is on page 5. Parallel structure A sentence (or list) is parallel if its coordinate elements follow the same grammatical form. Lists that are parallel are much easier for the reader to understand. Parallel structure Not parallel: The manager was bombarded with phone calls, sent several emails, and had everyone coming to visit her. Parallel: The manager was bombarded with phone calls, sent several emails, and visited by everyone. Not parallel: The hardest parts of his job were giving presentations and to write reports. Parallel: The hardest parts of his job were giving presentations and writing reports. Parallel structure in lists Software analyst May 2017 – August 2019 ● Developed web applications using Java. ● Designing UI for online bill-paying application. ● Have written automated tests in collaboration with the QA team. How can we improve this list? Parallel structure in lists Software analyst May 2017 – August 2019 ● Developed web applications using Java. ● Designed UI for online bill-paying application. ● Collaborated with the QA team to write automated tests. Trustworthy grammar sites ● Grammarist.com ● The OWL (Online Writing Lab) at Purdue ○ https://owl.english.purdue.edu/owl/ ○ General Writing Resources > Grammar ● The Center for Writing Studies at the University of Illinois ○ http://www.cws.illinois.edu/workshop/writers/ Proofreading Proofreading ● Check for missing or repeated words. ● Reading your writing aloud can help you find errors like this. ● Check your capitalization--don’t capitalize for emphasis, but make sure to capitalize proper nouns (names of software and other products, names of cities and countries, for example). ● Review your page design (including headings and subheadings). ● Double check margins, font size, and other design requirements. Commonly confused words Check carefully for homophones ● ● ● ● ● their, they’re, there to, too vary, very summery, summary whether, weather Commonly confused words and check for words that are similar and commonly confused ● ● ● ● loose, lose affect and effect (Affect is the verb. Effect is the noun) Its (plural possessive of it—The cat washed its tail.) It’s (contraction of it is—It’s a very fluffy tail.) Your spell check software can do a lot, but YOUR brain can do better. Conclusion Remember to... ● ● ● ● Plan and outline your document first. Use plain language and straightforward sentence construction. Keep page design, style, tone, and language consistent. Revise, edit, and proofread. Good technical writing resources Open Technical Communication (free digital textbook) https://alg.manifoldapp.org/projects/open-tc Purdue OWL (Online Writing Lab): Writing in Engineering https://owl.purdue.edu/owl/subject_specific_writing/writing_in_engineering/index. html The Mayfield Handbook of Scientific and Technical Writing http://web.mit.edu/course/21/21.guide/toc.htm Questions?
