4/2/2015 Pioneering 21st Century Electromagnetics and Photonics Technical Writing Raymond C. Rumpf, Ph.D. (915) 747-6958 [email protected] http://emlab.utep.edu Technical writing is hard work. There is no shortcut through it. You can only save yourself time by doing it right the first time. You will get better and faster with practice. 1 4/2/2015 Outline • Checklists • Steps to Technical Writing • Other Advice 4/2/2015 EM Lab Slide 3 Checklists 2 4/2/2015 Purpose of the Checklists The checklists are intended for you to work through in order to make sure that you have considered everything that is important to generate quality technical documents and graphics. http://emlab.utep.edu/academics.htm 4/2/2015 EM Lab Slide 5 Steps to Technical Writing 3 4/2/2015 Step 1 – You Have Something to Write About Some nugget of your research much have come to a conclusion that is important to share. 4/2/2015 EM Lab Slide 7 Step 2 – You Must Be an Expert On Your Topic To be an expert, you must have performed a comprehensive literature search so you are aware of the state-of-the-art and what your contribution is. 4/2/2015 EM Lab Slide 8 4 4/2/2015 Step 3 – What Are You Writing and Who is the Audience? Are you writing a journal article, a customer report, a poster, a presentation, etc.? Are you writing to members of the EM Lab, to your Ph.D. committee, the general public, to first graders, to other engineers/scientists? 4/2/2015 EM Lab Slide 9 Step 4 – Read and Archive All Requirements Are you required to write about a specific topic? Are you required to follow a specific outline? Are you required to have specific formatting? Is anything else required? 4/2/2015 EM Lab Slide 10 5 4/2/2015 Step 5 – Make an Outline Create a high level outline that will likely become your section headings. Make a bullet list in each section to identify the key points you need to make in that section. Review the outline for a logical flow of information and no redundancy. 4/2/2015 Abstract – A very brief summary of your document written in simple layperson language. Introduction – What is your topic? Why is it important? What have others done in this area? What is your unique contribution? How is your document organized to explain what you have done? Background – Discuss topics the reader needs in order to understand your document? Usually no need to discuss topics common in the literature. Body – The bulk of your document. Well-organized and methodical description of your topic(s). Discuss your procedures, present your results, draw conclusions, explain anomalies. Sufficient detail must be presented for the reader to reproduce your work. Conclusion – Why did you do? Why is it important? What new results did you generate? What meaningful conclusions were drawn from your results? Outline future work. EM Lab Slide 11 Step 6 – Write the Introduction Write the introduction first. This sets the stage for your entire document and will help you focus on the central message. • • • • • Introduce your main topic. Discuss why it is important. Discuss the history and what others have done on this topic. Introduce what you did and why your approach is unique and useful. For large documents, consider adding a paragraph to outline how your document is organized. 4/2/2015 EM Lab Slide 12 6 4/2/2015 Step 7a – Write the Body You will spend the majority of your time writing the body. Present your topics in a logical and well-planned order. Read similar documents for inspiration on how to organize. • • • • Describe your procedures. Present your results. Draw conclusions and discuss them. Explain anomalies. Say it once. Say it well. Don’t say it again. Don’t include meaningless messages or graphics. Include those in an Appendix if you really want to. 4/2/2015 EM Lab Slide 13 Step 7b – Sketch Figures First Write all the way up until you need to insert a figure. Roughly sketch the figure on paper. Revise the figure as you write the discussion of the figure. This will give better consistency and will more clearly convey the message to reader. Create the figure from your sketch with great care and attention to detail. 4/2/2015 EM Lab Slide 14 7 4/2/2015 Step 9 – Write the Abstract The abstract is a self-contained and short description of your technical document. Without sounding awkward, include as many key words and buzz words as possible. 4/2/2015 EM Lab Slide 15 Step 10 – Spell Check and Grammar Check This is an easy-to-forget step, but is very important. Sloppy documents are evaluated more poorly. 4/2/2015 EM Lab Slide 16 8 4/2/2015 Step 11 – Proofread Your Own Document Put your document aside if you have time. Proof it a few days or a week later. Read it aloud. You are more likely to catch mistakes this way. Make three passes: 1. Spelling, grammar, and wording errors. 2. Formatting and graphics. 3. High level message. Be sure your document passes the checklists! 4/2/2015 EM Lab Slide 17 Step 12 – Buddy Review Have your document reviewed by somebody not intimately aware of your research. Have the buddy make three passes: 1. Formatting, cleanliness, and professionalism. 2. High level message 3. Spelling, grammar, and wording mistakes. Have your buddy complete the checklists as well. 4/2/2015 EM Lab Slide 18 9 4/2/2015 Step 13 – Revise Document Revise your document based on buddy’s feedback. Make a quick pass through the revised document to ensure consistent formatting and that no graphics or tables jumped around leaving awkward white space. If the revisions were significant enough, go back to Step 10 and start the review process again from the beginning. 4/2/2015 EM Lab Slide 19 Step 14 – Help with English Consider using the university Library resources to help ensure proper English. To not waste the Library’s time, be sure document is as good as you can make it before taking it to them. 4/2/2015 EM Lab Slide 20 10 4/2/2015 Step 15 – Submit to Dr. Rumpf The last step is to submit to Dr. Rumpf. Dr. Rumpf will by far be your harshest reviewer. Because he cares. Really. Dr. Rumpf while reviewing technical documents from his students. 4/2/2015 EM Lab Slide 21 Other Advice 11 4/2/2015 Proofreading Proofreading is a unique and important skill. You will have a much more objective perspective about the technical document than the writer does. • Is the overall message clear and stated right upfront? • Does the document have a consistent, clear, and professional format? • Is the document easy to use? • Are the graphics clear? • Are the descriptions easy to understand? • Is the document complete? 4/2/2015 EM Lab Slide 23 Version Control It is best to save your documents with a version number at the end of the file name. Customer Report Feb 2015 v1.docx Create a new version when: 1. Revisions are significant. 2. You may want to resort back to a prior version. When editing somebody else’s document, add your name or initials to the end of the file name. Customer Report Feb 2015 v1 RCR.docx 4/2/2015 EM Lab Slide 24 12 4/2/2015 Best Practices for Editing Learn how to use “Track Changes” and Comments in MS Word. Make edits on written documents visible and obvious. Be helpful and specific. Avoid saying vague things like “reword this.” Instead, reword the text for the writer. Don’t just highlight mistakes, fix them. Review the Tables and Figures in addition to the text. 4/2/2015 EM Lab Slide 25 13
© Copyright 2024