ECE 582: Electrical and Computer Engineering Design I. Introduction, Technical Definitions, Documentation of Sources, Goals of Technical Writing

Transcription

1 ECE 582: Electrical and Computer Engineering Design I Introduction, Technical Definitions, Documentation of Sources, Goals of Technical Writing

2 Harrison Ben Smith Office Hours Office: Dreese Lab 601 Office Hours: 1½ hours after class Or by appointment,

3 Goals for this lecture Go over technical writing definitions Cover the goals of technical writing

4 Technical Definitions Chapter 3 in Pocket Book of Technical Writing by Finkelstein In technical writing, definition is the process by which one assigns a precise meaning to a term. Fink, p.25 (Qualifier +) Term = Classification + Differentiation

5 Technical Definitions II Qualifier: used when general context for a definition needs to be established up front Fink p.26 Classification: a general category in which the term fits Fink p.27 Differentiation: Narrowing the meaning of the term to just one possibility within the class. Fink p.29

6 For Example What is a stall? Needs qualifier: Stall can be used in many contexts (horse, aircraft, automobile, etc). (Qualifier +) Term = Classification + Differentiation Qualifier Term Class In aeronautics, a stall is a flight condition in which the lift produced is less than the weight of the airplane. Differentiation

7 Technical Definitions III Know you audience! Define VHDL for a medical imaging conference, but not for a hardware developer conference Definition Extensions (pg. 30) Further Definitions Define additional terms in definition Compare and Contrast Compare term (artifact) with other terms Classification Further classify artifact (i.e. The item is classified as ) Cause and Effect Demonstrate why something occurs Process List steps in a procedure Exemplification Give example where artifact is used

8 Documenting Sources Chapter 14 in Pocket Book of Technical Writing by Finkelstein.

9 Documenting Sources When to document sources Information is not common knowledge Idea used that you did not create Why document? Give formal credit Legal requirements Academic Standards Establish credibility

10 How to Document Sources Parenthetical documentation Source citation in parenthesis/brackets The development of a requirement specification described in [2] allows engineers to create products based on clearly defined criteria rather than whimsy. Alternatively: The development of a requirement specification [2] allows engineers to create products based on clearly defined criteria rather than whimsy.

11 How to Document Sources List of references at the end Correspond to citations List of sources at the end Not cited, but used to develop ideas

12 Examples Books [1] J. Eric Salt and Robert Rothery, Design for Electrical and Computer Engineers. New York, NY: John Wiley & Sons, INC., Journals [2] Changku Hwang, A Very Low Frequency, Micropower, Low Voltage CMOS Oscillator for Noncardiac Pacemakers, IEEE Trans. Circuits and Systems, vol. 42, Nov. 1995, pp Electronic References [3] PIC18F1230/1330 Data Sheet. Microchip, microchip.com/downloads/en/devicedoc/39758c.pdf (Accessed May 1, 2007)

13 Goals of Technical Writing Describe Mechanisms and Processes Documentation of some piece of technology (Mechanism) or some use of technology (Process) Document Design Process Progress Reports, Feasibility Reports, Project Reports, etc. Provide Instruction and Direction Read the Manual!

14 Goals of Technical Writing Impart Information Be Clear Be Terse Less is More Use the Word You Mean

15 Tricks and Strategies: Do's Separate content creation and editing For large documents, work on it every day Break each paragraph down and review every sentence Remember: less is more Peer review

16 Tricks and Strategies: Don'ts Don't add words that don't add needed meaning or detail Don't be flowery with your writing Don't use a more complicated word where a simpler word will do. Don't exaggerate or overstate Don't rely on spell-check Don't use it or this or the like

17 Lets work some examples... Describing an ATM: A ATM is an electronic machine that is made for allowing people to withdrawal money from their bank accounts electronically.

18 Lets work some examples... Describing MATLAB: MATLAB or 'The MATrix LABoratory' is a software tool leveraged by many engineers, scientists and researchers. Its primary goal is to help aid in the computation of complex and sophisticated linear algebra math problems.