Comprehensive Technical Writing Workshop by John Cole at The University of Texas at Dallas
Explore the world of technical writing with John Cole, an experienced instructor at The University of Texas at Dallas. This workshop covers the fundamentals of technical writing, including course objectives, programming, course outline, traits of technical writing, and what technical writing truly encompasses. Gain insights into the importance of clarity, conciseness, and accurate communication in technical writing and discover the distinction between technical writing and other forms of written communication.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
E N D
Presentation Transcript
Technical Writing Workshop Presented by John Cole The University of Texas at Dallas May 21, 2015 Technical Writing 1
Instructor: John Cole Completed MS in Computer Science from Illinois Institute of Technology 40 years of writing software in a large variety of industries Wrote my own software documentation Technical editor for Discover Visual Cafe 6 years as an adjunct (part-time) faculty member at UTD from January 2006 through May 2012, full time since then. Also taught at Collin College and, long ago, IIT Technical Writing 2
Course Objectives To introduce you to technical writing To make you a better writer in all areas Technical Writing 3
Programming and Writing Everyone in this country should learn how to program a computer because it teaches you how to think. -Steve Jobs Programming is necessarily precise, clear, and accurate. So is good technical writing. Technical Writing 4
Course Outline What is technical writing? Components of writing. Development Grammar Organization Style Document Design Technical Writing 5
Course Outline, Continued Traits of technical writing: Clarity Conciseness Accessible document design Audience recognition Accuracy Applications Technical Writing 6
What is Technical Writing? Technical writing is communication written for and about business and industry, focusing on products and services: how to manufacture them, market them, manage them, deliver them, and use them. It is denotative, not connotative. That is, it conveys precise information. Just the facts, ma am. Technical Writing 7
What Technical Writing Is Not Literature. It is not a story nor poetry. Journalism. It does not narrate an event nor report news. An essay. It does not express an opinion. Personal. While it may relate to the reader, it is not about your experiences. Technical Writing 8
Technical Writing None of this means it cannot be creative and sometimes even fun, but that is not its purpose Consider: Imagine a container that can hold a mixture of solid, liquid, and gas, and can let the gas out through a hole in the bottom. Technical Writing 9
Exercise Take 5 to 10 minutes to write a paragraph explaining why you decided to take this workshop Technical Writing 10
Why Learn it? Communication skills are essential. The best idea in the world is worthless unless you can communicate it Written communication is how ideas are preserved Nearly any job you get, no matter how technical, will require writing Technical Writing 11
Examples of Technical Documents Software manuals Company Web sites Your resume Instructions that come with a device A description of how you built something A bread recipe Help files This presentation Some e-mails Technical Writing 12
Writing in Computer Science Program specifications Project plans Use cases Comments in the code Research papers Technical Writing 13
Five Components of Writing Development Grammar Organization Style Document Design Technical Writing 14
Development Uses examples, anecdotes, testimony, data, research Start with overall objectives, then get into details Logical progression Technical Writing 15
Development For example, this is your overall objective: To assemble your robot chassis, you will need a Phillips screwdriver. Remove the parts from the package and make sure you have the following items: (the items are listed.) Now you can get to specifics, such as: Attach the motor to the motor mount using the machine screws, as shown in the diagram Technical Writing 16
Development Research often includes looking up information from various sources In computer science, it can involve looking at source code to determine what it really does Always keep track of your sources Technical Writing 17
Development Presentation of data is crucial Use paragraphs, but also charts, graphs, and tables Technical Writing 18
Grammar Always use correct grammar and spelling If you re not sure, look it up or get help from someone who knows. UTD has a writing center staffed with people who will be glad to help Technical Writing 19
Grammar Use second person; talk directly to your reader Avoid slang Don t be, like, real informal Explain acronyms. What is a CCN? There are many possible meanings for most TLAs. Technical Writing 20
Grammar If your word processor puts a wavy red line under a word, there is probably something wrong Don t shift tenses in the middle of a sentence A sentence has a subject and a predicate Don t run your sentences together this makes them hard to understand Make the antecedents of your pronouns clear Technical Writing 21
Grammar Use correct punctuation: Periods end sentences and commas separate dependent clauses Periods go inside quotation marks and parentheses Avoid semicolons in technical writing; they can make it too complex Technical Writing 22
Grammar Apostrophes are not used to form a plural: You will need four 2N3909 transistor s. Worst example: Altex Electronic s Apostrophes are used for contractions and possessives: Difficult case: its and it s U r not txting lol Technical Writing 23
Grammar Eye halve a spelling checker. It came with my PC. It plainly marks four my revue Mistakes I cannot sea. I ve run this poem threw it. I m sure your pleased two no, Its letter perfect in it s weigh My checker tolled me sew. Technical Writing 24
Group Exercise Fix the poem to be grammatically correct. Further exercise: Make the above sentence concise Technical Writing 25
What is a Paragraph? It is a sentence or group of sentences that expresses a single idea It often contains a statement, support for that statement, and a summary Technical Writing 26
Document Organization Provide an introduction, a body, and a conclusion Use a subject line and itemization of points rather than transitional words Uses topic sentences only when needed For some documents, alphabetize certain sections Technical Writing 27
Document Organization Put the most useful, general information first Follow it with detail Technical Writing 28
Style Use short, denotative words, short sentences, and short paragraphs Use diagrams and graphics if necessary Technical Writing 29
Document Design Use highlighting techniques, such as graphics, headings, subheadings, various fonts (but not too many), white space, bullets, etc. For sequential instructions, use numbered lists For longer documents, include a table of contents and an index For online documents, use hyperlinks Technical Writing 30
Document Design What is a font? How many are on this slide? Technical Writing 31
Exercise Write a single paragraph about the shirt (blouse, top, etc.) you re wearing right now. Be precise and descriptive. There is no length limit. Technical Writing 32
Five Traits of Technical Writing Clarity Conciseness Accessible document design Audience recognition Accuracy Technical Writing 33
Clarity Technical writing must be clear, easy to understand Who has ever gotten unclear instructions? Put that thing over there. The program didn t work. Or this homework assignment: Write a program that finds prime numbers. Technical Writing 34
Clarity Reporters Questions Who? Who is your audience? Are they beginners or experts? What? What do you want your audience to know? What do you want them to do? When? In many kinds of technical writing, things happen in a sequence. Where? Where will the work take place? How? How should the task be performed? Technical Writing 35
Clarity Avoid imprecise words: many, few, short, often, recently, thin, etc. Use precise words and terminology: Connect a 20K-ohm, -watt resistor in series with the light sensor Don t block the user interface thread for more than 2 seconds Use four inches of 26-gauge black wire Technical Writing 36
Clarity Front-load your sentences with important information: Unfortunately, your program has timed out. Network connection unavailable. Call 5555 for technical support. Technical Writing 37
Clarity I had eggs scrambled with cheddar cheese and toast for breakfast this morning. Were the eggs scrambled with cheese and toast? Keep terms consistent. For example, I often use method and function interchangeably, but there really is a difference. Technical Writing 38
Conciseness Concise means expressing much in few words Keep it short and to the point Its opposite is pleonasm, which is using many words where few will do Documents must often fit in a specific physical space Resume must be one page Car owner s manual must fit in glovebox Technical Writing 39
Conciseness Counterexample In order to facilitate an efficient meeting and fuel thought processes prior to June 25, I want to provide you with a brief overview of discussions recently carried out at the director and manager level within the process. These discussions involved personnel from Accounts Payable, Information Services, Procurement/Materials Management, Financial Systems, and Property Accounting, centering on a proposed framework for managing process improvement moving forward. Technical Writing 40
Exercise Rewrite the previous slide to be concise and clear. Technical Writing 41
Conciseness Use short words instead of sesquipedalianisms Use this Rather than this Use Utilize Try Endeavor End Terminate Do or perform Accomplish Work Collaborate Soon Presently Job Employment Technical Writing 42
Conciseness From the department of redundancy department: We collaborated together on the project. The system will cost the sum of $30,000. The other alternative menu item is fish. We could not find the file you requested. Technical Writing 43
Conciseness Avoid prepositional phrases: Switches modes quickly not Switches modes at a high rate of speed. (What else should you do with this?) Avoid passive voice: The system processes approximately 2000 records per minute not Approximately 2000 records per minute are processed by the system. Technical Writing 44
Exercise Spend a minute or so looking at your computer. Then write instructions for disassembling it. Technical Writing 45
Accessible Document Design Document design refers to the physical layout Often, technical documents are used for reference, not meant to be read in their entirety Your reader may not even be interested in the subject Technical Writing 46
Document Design Long documents require a table of contents and an index. For example, programming manuals, patents, etc. Use hyperlinks in online documents Use bookmarks in PDFs Technical Writing 47
Document Design Don t use paragraphs that look like a wall of words. Use tables to present information clearly: Grading Criteria Program works according to your specification and does not crash under testing. Program uses the two principles you outlined in your description. Clean object-oriented design 50 points 30 points 10 points Program comments and naming conventions 10 points Technical Writing 48
Know Your Audience There are three different kinds of audiences: High-tech peers these are people in the same profession at roughly the same level as the writer. The PCBUS manual is written at this level. Low-tech peers These are people who may not have the same level of expertise as you but they need to understand the subject. The summary of a software design document written for a manager is an example. Technical Writing 49
Know Your Audience Everyone else The person setting up a TV set or video recorder, the person who just wants to use her computer to send e-mail or play games, and the person assembling a bicycle are all in this category. Technical Writing 50
