Writing a Technical Document

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.