1 / 37

Writing a Technical Document

Writing a Technical Document. Gail Palmer School of Electrical and Computer Engineering Georgia Institute of Technology. Acknowledgements. A special thank you to the following authors who have allowed me to use examples from their technical papers: Thomas G. Habetler Ronald G. Harley

yeo-diaz
Download Presentation

Writing a Technical Document

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  1. Writing a Technical Document Gail Palmer School of Electrical and Computer Engineering Georgia Institute of Technology

  2. Acknowledgements A special thank you to the following authors who have allowed me to use examples from their technical papers: • Thomas G. Habetler • Ronald G. Harley • Salman Mohagheghi* • Wiehan le Roux* • Jason R. Stack* • Rangarajan M. Tallam* *Former students in ECE 8020 Professional Communication Skills in the School of Electrical and Computer Engineering at the Georgia Institute of Technology.

  3. Engineers as Technical Writers • Entry-level engineers spend 40% of their time writing. Technical Writing Time

  4. The Disconnect in Technical Writing Audience’s Interests Abstract Conclusion Citations and References Analytical Graphics

  5. The Disconnect in Technical Writing Author’s Focus Body Appendices Citations and References Detailed Graphics

  6. Method 1 for Solving the Disconnect • Reverse the traditional order of sections: Introduction Body Results Conclusions

  7. Method 2 for Solving the Disconnect • Add an effective abstract: • Has 2 parts • Foreword • Conclusion • Contains 75-200 words in 5-10 sentences • Is written in paragraph form

  8. Writing to Connect with the Audience Abstract and Introduction Conclusion Analytical Graphics Citations and References Body Appendices

  9. IEEE Technical Document • Document • Sections • Paragraphs • Sentences

  10. The Abstract: Part 1 – The Foreword 1 Context 2 Problem 3 Working Thesis or Task 4 Object and Scope of the Document Have you included allnecessary background information? Why is it important? What will you do to solve the problem? Are these stated briefly?

  11. The Abstract: Part 2 – The Results What happened when youcompleted the task ? 1 Results 2 Conclusions What do the results mean? 3 Perspectives Where do yougo from here?

  12. Types of Abstracts • Descriptive abstract = PELS digest • Written before the project is completed • Focuses on the problem and the working thesis • Informative abstract • Written after the project is completed • Focuses on the results and conclusions of the project

  13. Outlining a Technical Document 1 Group Similar Items 2 Order Items in Designated Groups 3 Avoid CommonLogical Problems 4 Choose an Outline Format

  14. The Introduction 1 State Purpose and Scope of the Document 2 Define the Problem 4 Give Reasons forYour Approach tothe Problem 3 Address PreviousWork in the Field

  15. The Conclusion 1 Present andInterpret Results 2 Assess the Success of the Task/Working Thesis 4 May Make Recommendations 3 Review the Key Points

  16. An Effective Technical Document • Addresses the audience’s needs • Clear • Concise • Consistent • Correct • Coherent • Respects constraints • Conveys a maximum number of messages given the constraints

  17. Clarity in a Technical Document Analyze the audience: ECE 8020 Students = Experts Graphics Abstract Forecasting Context/Purpose Direct Language Table of Contents Section Headings Citations/ References and Word Choice

  18. Conciseness in a Technical Document • Narrow the scope of the document • Introduction • Outline • Use graphics • Eliminate unnecessary material • Sections • Paragraphs • Sentences • Words

  19. Consistency in a Technical Document • Word choice • Formatting • Margins • Headings • Mechanics • Capitalization • Enumeration • Spelling • Use of numbers • Style • Person • Tone

  20. Correctness in a Technical Document Clear Focus on the Problem Topic Coverage Documentary Paragraph Development Sentence Structure Word Choice Stylistic Mastery of the Subject and Its Vocabulary Analysis of Data Technical

  21. Coherence in a Technical Document • Make an outline for yourself • Provide a map of the document for readers to follow: • Create section headings from the outline • Organize and develop paragraphs • Use forecasting • Draft a first version of the document: • Include appropriate amount of background information • Explain concepts in detail – may be included in the appendices • Use technical terms • Provide analytical graphics

  22. Provide a Map of the Document Section Headings Transitions Transitions Document Transitions Sentence Structure Paragraph Development

  23. Use Forecasting Use forecasting in the introductionand in section openings. What is the context of the discussion? Present the WHOLE before the parts! Present the WHOLE before the parts! What are the details?

  24. Drafting a Technical Document 1 Draft onthe Outline 2 Start with theEasiest Topics 3 Do Not ResearchInformation or Revise 4 Include NewMaterial

  25. Basic Patterns of Information • Chronological • Spatial • General to specific • More important to less important • Comparison and contrast • Problem-methods-solution • Cause and effect

  26. IEEE Technical Document • Document • Sections • Paragraphs • Sentences

  27. Creating Section Headings 1 Follow theOutline 2 Repeat Key Termsin Section Headings 3 Guide Readersthrough the Material

  28. Repeat Key Terms in Section Headings • Paper title: Stator Winding Turn-Fault Detection for Closed-Loop Induction Motor Drives • Section headings: • Introduction • Detection of Turn-Faults in Open-Loop Drives • Detection of Turn-Faults in Closed-Loop Drives • Detection of Turn Faults at Low Stator Frequencies • Experimental Results • Conclusions

  29. IEEE Technical Document • Document • Sections • Paragraphs • Sentences

  30. Developing a Paragraph • What does a paragraph do? • Introduces messages • Supports the messages • Provides a smooth transition to the next message

  31. Organizing a Paragraph • Topic sentence – states the primary idea of the paragraph • Is required • Is frequently the first sentence in the paragraph • Supporting sentences – support the theme of the topic sentence • Transitional devices – are essential to paragraph and document cohesion • Repetition of key words • Demonstrative pronouns (adjectives) followed by nouns • Transitional words and phrases

  32. Sample Transitional Words and Phrases • Cause and effect: consequently, therefore, hence • Sequence: first, second, next, and, finally • Comparison or contrast: similarly, although, but • Example: of course, in fact, for example, • Purpose: to this end, for this reason • Time or location: now, soon, later, here, above

  33. IEEE Technical Document • Document • Sections • Paragraphs • Sentences

  34. Sentence Structure 2 Put the Most Important Facts in theIndependent Clause 1 Move from Knownto UnknownInformation 4 Use PositiveStatements 3 Use the Active Voice for Verbs

  35. Move from Known to Unknown Information Known Information: • Research indicates that a healthy bearing will possess a film of lubrication ranging from 0.2 μm to 2.0 μm thick at normal operating speeds. • Given this thickness of lubrication, EDM currents can be caused by 60 Hz shaft voltages as low as 0.2 V to 2 V peak. • Another study suggests that it is not the magnitude of the EDM current, but rather the current density within the bearing that directly determines the rate of failure. Unknown Information: Unknown Information:

  36. Technical Writing Resources • http://users.ece.gatech.edu/~gpalmer/ece8020/index.shtml • http://ewh.ieee.org/soc/es/Aug1996/030/cd/write/begin.htm • L. C. Perelman, J. Paradis, and E. Barrett. The Mayfield Handbook of Technical & Scientific Writing. Mountain View, California: Mayfield Publishing Company, 1998. • D. Beer and D. McMurrey. A Guide to Writing as an Engineer. New York: John Wiley & Sons, Inc., 1997. • W. Strunk, Jr. and E.B. White. The Elements of Style, Fourth Edition. New York: Longman, 2000.

More Related