Lecture 5: Documentation - NGN110 - PDF

Lecture 5: Documentation NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul Introduction Engineers have the responsibility to inform people of findings & developments As a design engineer, you must convince your boss that your idea is worth the time and money required to develop it. NG...

Lecture 5: Documentation NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul Introduction Engineers have the responsibility to inform people of findings & developments As a design engineer, you must convince your boss that your idea is worth the time and money required to develop it. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 2 Engineering Communication  Three different ways of communication in Engineering Oral Communication Group Presentation Individual Presentation Written Communication Graphical Communication Formal Presentation Informal Presentation NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 3 Engineering Communication  Three different ways of communication in Engineering Oral Communication Written Communication Design Documents Progress Reports Memo Emails Research Reports Feasibility Reports Graphical Communication Proposals Lab Reports Letters NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul Manuals Thesis American University of Sharjah Page 4 Engineering Communication  Three different ways of communication in Engineering Oral Communication Written Communication Graphical Communication Sketching Diagrams Computer Aided Drafting Data & Graphs NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 5 Why is Written Communication Important? - Example  Space Shuttle Challenger (1986) NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 6 Why is Written Communication Important? - Example  Space Shuttle Challenger (1986)  Cause of explosion  Failure of the O-rings in the solid rocket boosters NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 7 Why is Written Communication Important? - Example  Space Shuttle Challenger (1986)  Cause of explosion   Failure of the O-rings in the solid rocket boosters Engineers   knew about the problem but failed to communicate its seriousness NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 8 Written Communication  Ask yourself the following questions before your start writing your report:  Who will read the report ?  Why do they want to read the report ?  What’s their level of knowledge on my subject?  Will the report leave them with a positive or a negative attitude ?  Will the report provide them with the desired information ? Know Your Audience NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 9 7 Tips For Effective Writing 1- Get to the point Good message will state its purpose in the first sentence (or possibly the second) “I am writing you this message to inform you … “ NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 10 7 Tips For Effective Writing 1- Get to the point – Example An engineer writes to his boss to ask for permission to attend a conference John, As you know, the society of mechanical engineers is holding a conference on lightweight composites in Dayton, Ohio at the end of June. I think someone from the company should attend the meeting. Composites are great alternatives to steels. The conference will be held at Dayton Vista. I’ve spoken to the travel agent and found that the ticket will cost $400. Hotel will be $80 per day and registration is $100. Let me know what you think. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 11 7 Tips For Effective Writing 1- Get to the point – Example Harry never got to go the conference Harry never stated explicitly in his first sentence that it was he (Harry) who wanted to attend the conference He should have included “I would like permission to attend the upcoming conference …” John (the Boss) went to the conference! NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 12 7 Tips For Effective Writing 2- Distinguish between facts and opinions Your report should differentiate between facts that have been supported by evidence and your personal opinion: Stating that a BMW is superior to a Mercedes is your opinion. Stating that, based on cost, consumer surveys and the various innovative features, several researchers in the area agree that BMW is superior to a Mercedes is a fact supported by evidence. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 13 7 Tips For Effective Writing 3- Express yourself clearly Ambiguity, vagueness & lack of coherence may leave a sentence open to several interpretations: For example: “before buying the computers from the new companies, they should meet our approval” …… who is “They” – the computers or the companies ?? NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 14 7 Tips For Effective Writing 4- Be specific whenever possible Being specific eliminates the need for asking questions – compare the following: The test program took several weeks to complete. The test program took four weeks to complete. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 15 7 Tips For Effective Writing 5- Use active verbs Depending on the style you follow, you could use one of the following: Active: Subject performs the action expressed in the verb Passive: Subject receives action expressed in the verb The oil is compressed by a piston (passive) The piston compresses the oil (active) NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 16 7 Tips For Effective Writing 6- Be coherent in your writing Within one section, paragraphs should build on one another. Within one paragraph, a given sentence should relate to the one before it and the one following it. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 17 7 Tips For Effective Writing 7- Appearance is important The appearance of your report influences the reader: Use ample margins (1” all around) Use a 12-point typeface, Times New Roman font Leave space between paragraphs Capitalize or bold titles etc. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 18 What Should A Progress Report Include?  A progress report should tell the reader 3 things  Review the problem your solving Reference the original proposal by number/title Indicate when it was accepted Describe problem that prompted the proposal  Describe the solution offered in the original proposal Including tasks involved in implementing solution List the milestones associated with each task  Evaluate how well your doing each task Provide overall assessment of your progress Mention if your within timeframe and cost constraints NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 19 Outline: Progress Report Introduction Purpose – why are you writing the progress report? Status Conclusion NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul Background – what is the context of the project? American University of Sharjah Page 20 Outline: Progress Report Introduction Status Conclusion Tasks Completed For each task - What was the task? - What was accomplished? - How long did it take? - What difficulties, if encountered? Tasks Remaining For each task - What is the task? - What has yet to be accomplished? - What are the strategy to do it? - What are the risks involved? NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 21 Outline: Progress Report Summary – what is your appraisal of current status? Introduction Status Conclusion Evaluation – how would you evaluate the progress made so far? Forecast – What is your forecast for completing this project? Contact – who is the contact for this progress report? NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 22 Outline: Standard Report Cover/Title Page 1) Title Abstract Table of Contents List of Figures 2) Name, title & organization to which the report is submitted (your professor, the course number) List of Tables Introduction Body 3) The name, title & organization which completed the work (your ID) Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul 4) Submission date American University of Sharjah Page 23 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures A brief paragraph indicating the purpose and result of the effort being presented List of Tables Introduction Body Allow others to decide whether they want to obtain the complete report. Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 24 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 25 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body The page numbers that start the various sections are included in the TOC (as in most textbooks). Should fit neatly on the page: neither congested nor spaciously loose. Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 26 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 27 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures The list of figures precedes the list of tables. List of Tables Introduction Body Both contain the page numbers where the various figures and tables can be found. Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 28 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 29 Outline: Standard Report Cover/Title Page Abstract Table of Contents Describes the purpose of the report. List of Figures List of Tables Introduction Body Conclusions Presents a brief overview of the project. Gives background information and may explain the organization of the report. Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 30 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body The principal section of the report. Includes: background material, techniques used, assumptions, setup, program, experiments, results. Conclusions Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 31 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body Conclusions Gives the reasons for conducting the study and the purpose of the report. Explains what was found from the study. Provides recommendations for what should be done as a result of the findings (you must be able to sell your idea). Appendices NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 32 Outline: Standard Report Cover/Title Page Abstract Table of Contents List of Figures List of Tables Introduction Body Conclusions Appendices Are used to avoid interrupting your descriptions so that it can flow smoothly. What is in the appendix completes the story by showing all what was done. Those who want to know all the details of your study can read it. May include computer programs, tables of experimental data or sample calculations (proofs). It should not contain information that is essential to one’s understanding of the report. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 33 Why Reference Sources?  For three reasons  Meet legal requirements Using copyrighted material  Meet academic standards You must document any non-original ideas, except those that represent common knowledge in the field  Establish credibility Support your conclusions which are not based on common knowledge NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 34 References  Always list all references that were cited  References can include      Books, magazines Papers in journals, conferences, etc. Technical reports Websites People NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 35 References  Order of entries  Authors names (First initial, Last Name) Title of paper Conference/journal name Location Page number Publication year (month – optional)  e.g.      F. Aloul, I. Markov, and K. Sakallah, “Efficient Symmetry Breaking for Boolean Satisfiability,” Design Automation Conference (DAC), Anaheim, California, pp. 271-282, June 2003. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 36 References  Order of entries       Authors names (First initial, Last Name) Title of paper Conference/journal name Location Page number Publication year (month – optional)  e.g. F. Aloul, “Personal Interview,” American University of Sharjah, Sharjah, UAE, October 2013.  “NGN110 Competition Video Fall 12,” YouTube Video, Dec 2012. Available at: http://www.youtube.com/watch?v=xZvVvOPOwyc NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 37 References  In the body of the report: According to , SAT problems in CAD contain significant amounts of symmetries.  In the References: F. Aloul, I. Markov, and K. Sakallah, “Efficient Symmetry Breaking for Boolean Satisfiability,” Design Automation Conference (DAC), Anaheim, California, pp. 271-282, June 2003. M. Bilani, “Survey of Boolean Satisfiability Solvers,” International Workshop on Logic Synthesis, Las Vegas, pp. 2-9, May 2001. NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 38 References NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 39 NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 40 Visuals  Definition  Visual presentation of ideas  Large amounts of information can be handled quickly and efficiently when sense of sight is used  Visuals include     Figures, diagrams, drawings Illustrations, graphs, charts Maps, photos, tables … NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 41 Guidelines For USING Visuals  Include them only when needed  Reference every visual in text  Explain the significance of every visual  Number and title all visuals  Labels and captions in visual should match the text discussion  Document copyrighted visuals NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 42 Three Guidelines For DESIGN Of Visuals  Reproducibility   Simplicity    e.g. will the report be duplicated using a single-color ink? Putting everything in the same chart may make it very complex to understand Solution: Break down into parts Accuracy  Visuals should accurately portray the information NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 43 Guidelines For DESIGN Of Visuals  Reproducibility  Solution: Use shading Countries en route Pick up and delivery regions Regios not served Delivery by sea transportation 3 1-Germany 2-Benelux 3-England 4-France 5-Spain 2 1 4 5 1-Turkey 2-Bulgaria 3-Romania 4-Hungary 5-Austria 4 3 2 5 NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul 1 American University of Sharjah Page 44 Five Types Of Visuals   Diagrams Graphs       Line charts Bar/column charts Pie charts Schematics Images Tables NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 45 Types Of Visuals - Graphs    Relationship among sets of numbers Great for presenting statistical information 3 types    Line charts Bar/column charts Pie charts NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 46 Types Of Visuals – Line Chart  Normally,   Vertical Y-axis plots dependent data points Horizontal X-axis plots independent data points 450,000 Number of Accidents 400,000 387,533 350,000 344,643 300,000 279,663 250,000 233,803 208,823 200,000 171,741 150,000 142,145 110,207 107,651 100,000 50,000 55,256 60,705 115,295 103,758 92,468 63,473 46.264 36.960 40.023 1997 1996 1995 1994 1993 1992 1991 1990 1989 1988 1987 1986 1985 1984 1983 1982 1981 1980 0 Years Figure 1. Accidents by Years NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 47 Types Of Visuals – Bar and Column Chart   Excellent for comparing discrete variables Use   Bar chart – when value labels are too long to fit on horizontal axis Column chart – when value labels are short enough to fit well on the horizontal axis Figure 2: Nationality Distribution at Eng School Nationality Africa USA Europe Asia Middle East 0 2 4 6 8 10 12 Bar Chart Number NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 48 Types Of Visuals – Bar and Column Chart Frequency (%) Column Chart 60 45 1998 30 1999 15 0 0.8 1.15 1.5 1.85 2.2 2.55 2.9 time (days) NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 49 Types Of Visuals – Pie Chart   Useful for showing relative proportions They don’t provide the same degree of precision as line, bar, or column charts Figure 2: Nationality Distribution in Eng School Middle East Asia Europe USA Africa NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 50 Adding Visual Interest To Charts  Three-dimensional charts? Figure 2: Nationality Distribution at Eng School 10 9 8 Number 7 6 5 4 3 2 1 0 Middle East Asia Europe USA Africa Nationality NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 51 Adding Visual Interest To Charts  Three-dimensional charts? Figure 2: Nationality Distribution in Eng School Middle East Asia Europe USA Africa NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 52 Types Of Visuals – Schematics  Represent the   System’s structure or procedures involved in a process Export Loading / Unloading Time (LUE) Export Idle Time (IE) Arrival to Export Loading Point Departure from Import Unloading Point Departure from Export Loading Point Arrival to Import Unloading Point Complete Trip Time (tC) Export Transit Time (TE) Import Transit Time (TI) Arrival to Export Unloading Point Export Loading / Unloading Time (LUE) Import Loading / Unloading Time (LUI ) Departure from Import Loading Point Departure from Export Unloading Point NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul Import Idle Time (II) Arrival to Import Loading Point Import Loading / Unloading Time (LUI) American University of Sharjah Page 53 Types Of Visuals – Images  Visual reproductions that actually reproduce the appearance of objects (e.g. photographs) NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 54 Types Of Visuals – Tables  Orderly arrangement of data and information in columns and rows Number of Accidents Ye ar 1998 1999 Number of Accidents / 1.000.000 veh.km 1998 1999 Fatal or Injury Accidents 6 9 1.3 1.9 Property Damage Accidents 26 40 5.7 8.2 T otal Accidents 32 49 7.0 10.1 NGN110: Introduction to Engineering and Computing Dr. Fadi Aloul American University of Sharjah Page 55