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 American University of Sharjah

Dr. Fadi Aloul Page 2
Engineering Communication

 Three different ways of communication in Engineering

Oral Written Graphical

Communication Communication Communication

Group Formal
Presentation Presentation

Individual Informal
Presentation Presentation

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 3
Engineering Communication

 Three different ways of communication in Engineering

Oral Written Graphical

Communication Communication Communication

Design Memo
Proposals
Documents Emails

Progress Research Lab

Manuals
Reports Reports Reports

Feasibility
Letters Thesis
Reports

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 4
Engineering Communication

 Three different ways of communication in Engineering

Oral Written Graphical

Communication Communication Communication

Sketching Computer
Diagrams Aided Drafting

Data &
Graphs

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 5
Why is Written Communication Important? - Example

 Space Shuttle Challenger

(1986)

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 19
Outline: Progress Report

Purpose – why are you

Introduction writing the progress
report?
Status
Conclusion Background – what is the
context of the project?

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 20
Outline: Progress Report

Tasks Completed
For each task
- What was the task?
- What was accomplished?
Introduction - How long did it take?
- What difficulties, if encountered?
Status Tasks Remaining
For each task
Conclusion - 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 American University of Sharjah

Dr. Fadi Aloul Page 21
Outline: Progress Report

Summary – what is your

appraisal of current status?

Evaluation – how would you

Introduction
evaluate the progress made
Status so far?

Conclusion Forecast – What is your forecast

for completing this project?

Contact – who is the contact for

this progress report?

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 22
Outline: Standard Report
Cover/Title Page
1) Title
Abstract
2) Name, title & organization
Table of Contents
to which the report is
List of Figures submitted (your professor,
the course number)
List of Tables
Introduction 3) The name, title &
organization which
Body completed the work (your
ID)
Conclusions
Appendices 4) Submission date
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul Page 23
Outline: Standard Report
Cover/Title Page
Abstract
Table of Contents
A brief paragraph indicating the
List of Figures purpose and result of the
effort being presented
List of Tables
Introduction Allow others to decide whether
they want to obtain the
Body complete report.

Conclusions
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul 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 American University of Sharjah
Dr. Fadi Aloul Page 25
Outline: Standard Report
Cover/Title Page
Abstract
Table of Contents The page numbers that start the
various sections are included
List of Figures in the TOC (as in most
textbooks).
List of Tables
Introduction Should fit neatly on the page:
neither congested nor
Body spaciously loose.
Conclusions
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul 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 American University of Sharjah
Dr. Fadi Aloul Page 27
Outline: Standard Report
Cover/Title Page
Abstract
Table of Contents
The list of figures precedes the
List of Figures list of tables.
List of Tables
Both contain the page numbers
Introduction where the various figures and
tables can be found.
Body
Conclusions
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul 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 American University of Sharjah
Dr. Fadi Aloul Page 29
Outline: Standard Report
Cover/Title Page
Abstract
Describes the purpose of the
Table of Contents report.
List of Figures
Presents a brief overview of the
List of Tables project.
Introduction
Gives background information
Body and may explain the
organization of the report.
Conclusions
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul Page 30
Outline: Standard Report
Cover/Title Page
Abstract
Table of Contents
The principal section of the
List of Figures report.

List of Tables Includes: background material,

Introduction techniques used,
assumptions, setup, program,
Body experiments, results.

Conclusions
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul Page 31
Outline: Standard Report
Cover/Title Page
Abstract Gives the reasons for
conducting the study and the
Table of Contents purpose of the report.

List of Figures Explains what was found from

List of Tables the study.

Introduction Provides recommendations for

what should be done as a
Body
result of the findings (you
Conclusions must be able to sell your
idea).
Appendices
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul Page 32
Outline: Standard Report
Cover/Title Page Are used to avoid interrupting your
descriptions so that it can flow
Abstract smoothly.

Table of Contents What is in the appendix completes

the story by showing all what was
List of Figures done. Those who want to know all
the details of your study can read
List of Tables it.

Introduction May include computer programs,

tables of experimental data or
Body sample calculations (proofs).
Conclusions It should not contain information that
is essential to one’s
Appendices understanding of the report.
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 37
References

 In the body of the report:

According to [1], SAT problems in CAD contain significant
amounts of symmetries.

 In the References:

[1] F. Aloul, I. Markov, and K. Sakallah, “Efficient Symmetry

Breaking for Boolean Satisfiability,” Design Automation
Conference (DAC), Anaheim, California, pp. 271-282, June
2003.

[2] 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 American University of Sharjah
Dr. Fadi Aloul Page 38
References

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 39
NGN110: Introduction to Engineering and Computing American University of Sharjah
Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 42
Three Guidelines For DESIGN Of Visuals

 Reproducibility
 e.g. will the report be duplicated using a single-color ink?

 Simplicity
 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 American University of Sharjah

Dr. Fadi Aloul 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

1-Germany 1-Turkey
3 2
1 2-Benelux 2-Bulgaria
3-England 3-Romania
4-France 4-Hungary
5-Spain 5-Austria
4 4
5
3

1
5

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 44
Five Types Of Visuals

 Diagrams
 Graphs
 Line charts
 Bar/column charts
 Pie charts
 Schematics
 Images
 Tables

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 46
Types Of Visuals – Line Chart

 Normally,
 Vertical Y-axis plots dependent data points
 Horizontal X-axis plots independent data points

450,000
400,000 387,533

350,000 344,643
Number of Accidents

300,000
279,663

250,000 233,803
208,823
200,000
171,741
150,000 142,145
110,207 107,651 115,295
100,000 92,468
103,758
55,256 60,705
63,473
50,000 46.264
36.960 40.023

0
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
Years
Figure 1. Accidents by Years

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul 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

Africa

USA
Nationality

Europe

Asia

Middle East

0 2 4 6 8 10 12 Bar Chart
Number

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 48
Types Of Visuals – Bar and Column Chart

Column Chart

60
Frequency (%)

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 American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 50
Adding Visual Interest To Charts

 Three-dimensional charts?
Figure 2: Nationality Distribution at Eng School

10

6
Number

4
3

2
1
0
Middle
Asia
East Europe
USA
Africa
Nationality

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul 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 American University of Sharjah

Dr. Fadi Aloul Page 52
Types Of Visuals – Schematics

 Represent the
 System’s structure or
 procedures involved in a process

Export Arrival to Export Idle Departure from Import

Loading / Unloading Export Time Import Loading / Unloading
Time (LUE) Loading Point (IE) Unloading Point Time (LUI )

Departure from Export Arrival to Import

Loading Point Unloading Point

Complete Trip
Export Transit Import Transit
Time (TE)
Time Time (TI)
(tC)

Arrival to Export Departure from Import

Unloading Point Loading Point

Export Import Idle Arrival to Import

Departure from
Loading / Unloading Time Import Loading / Unloading
Export
Time (LUE) (II) Loading Point Time (LUI)
Unloading Point

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 53
Types Of Visuals – Images

 Visual reproductions that actually reproduce the

appearance of objects (e.g. photographs)

NGN110: Introduction to Engineering and Computing American University of Sharjah

Dr. Fadi Aloul Page 54
Types Of Visuals – Tables

 Orderly arrangement of data and information in columns

and rows

Number of
Number of
Accidents /
Accidents
1.000.000 veh.km
Ye ar 1998 1999 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 American University of Sharjah

Dr. Fadi Aloul Page 55