writing a technical document l.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
Writing a Technical Document PowerPoint Presentation
Download Presentation
Writing a Technical Document

Loading in 2 Seconds...

play fullscreen
1 / 37

Writing a Technical Document - PowerPoint PPT Presentation


  • 118 Views
  • Uploaded on

Writing a Technical Document. 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*

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Writing a Technical Document' - topper


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.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
acknowledgements
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.

engineers as technical writers
Engineers as Technical Writers
  • Entry-level engineers spend 40% of their time writing.

Technical Writing Time

the disconnect in technical writing
The Disconnect in Technical Writing

Audience’s

Interests

Abstract

Conclusion

Citations and References

Analytical Graphics

the disconnect in technical writing5
The Disconnect in Technical Writing

Author’s

Focus

Body

Appendices

Citations and References

Detailed Graphics

method 1 for solving the disconnect
Method 1 for Solving the Disconnect
  • Reverse the traditional order of sections:

Introduction

Body

Results

Conclusions

method 2 for solving the disconnect
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
writing to connect with the audience
Writing to Connect with the Audience

Abstract and Introduction

Conclusion

Analytical Graphics

Citations and References

Body

Appendices

ieee technical document
IEEE Technical Document
  • Document
  • Sections
  • Paragraphs
  • Sentences
the abstract part 1 the foreword
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?

the abstract part 2 the results
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?

types of abstracts
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
outlining a technical document
Outlining a Technical Document

1

Group

Similar Items

2

Order Items in Designated Groups

3

Avoid CommonLogical Problems

4

Choose an Outline Format

slide14

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

the conclusion
The Conclusion

1

Present andInterpret Results

2

Assess the Success of the Task/Working Thesis

4

May Make Recommendations

3

Review the Key Points

an effective technical document
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
slide17

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

conciseness in a technical document
Conciseness in a Technical Document
  • Narrow the scope of the document
    • Introduction
    • Outline
  • Use graphics
  • Eliminate unnecessary material
    • Sections
    • Paragraphs
    • Sentences
    • Words
consistency in a technical document
Consistency in a Technical Document
  • Word choice
  • Formatting
    • Margins
    • Headings
  • Mechanics
    • Capitalization
    • Enumeration
    • Spelling
    • Use of numbers
  • Style
    • Person
    • Tone
correctness in a technical document
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

coherence in a technical document
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
provide a map of the document
Provide a Map of the Document

Section

Headings

Transitions

Transitions

Document

Transitions

Sentence Structure

Paragraph Development

use forecasting
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?

drafting a technical document
Drafting a Technical Document

1

Draft onthe Outline

2

Start with theEasiest Topics

3

Do Not ResearchInformation or Revise

4

Include NewMaterial

basic patterns of information
Basic Patterns of Information
  • Chronological
  • Spatial
  • General to specific
  • More important to less important
  • Comparison and contrast
  • Problem-methods-solution
  • Cause and effect
ieee technical document26
IEEE Technical Document
  • Document
  • Sections
  • Paragraphs
  • Sentences
slide27

Creating Section Headings

1

Follow theOutline

2

Repeat Key Termsin Section Headings

3

Guide Readersthrough the Material

repeat key terms in section headings
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
ieee technical document29
IEEE Technical Document
  • Document
  • Sections
  • Paragraphs
  • Sentences
developing a paragraph
Developing a Paragraph
  • What does a paragraph do?
    • Introduces messages
    • Supports the messages
    • Provides a smooth transition to the next message
organizing a paragraph
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
sample transitional words and phrases
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
ieee technical document33
IEEE Technical Document
  • Document
  • Sections
  • Paragraphs
  • Sentences
slide34

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

move from known to unknown information
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:

technical writing resources
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.