Professionally Speaking
A seminar on
Teamwork and Collaboration Communication skills
Report writing
By Dr. Hussein Sharafeddin 11/23/2012
LIU SOE graduate seminar series
1
Too late to talk about learning principles?? WYSIWIG -- sounds familiar? How about WYSIWYL Effort vs. thoroughness
Learning Principles!
2
“He who knows not and knows not that he knows not is a fool—shun him. He who knows not and knows that he knows not is a child—teach him. He who knows and knows not that he knows is asleep—wake him. He who knows and knows that he knows is wise—follow him.”
Learning Principles!
3
1. Technical writing and its importance in the workplace
2. Technical writing characteristics 3. Resources 4. The writing process, resources, revisions 5. Collaboration 6. Including figures, tables, code.. 7. Summary and abstract 8. English mistakes 9. Real examples
Plan
4
You have engaged in technical writing or technical communication if you have:
• Given someone written directions or drawn a map to your home
• Told someone how to change the oil in a car
• Written quick instructions for using a fax machine
6 You Are a Technical Writer
5
What Is Technical Writing?
in your Resume’ Excellent communication skills
16 You Are a communicator
6
Your thesis as a technical document:
Helps polish your written communication skills pass along information to others keep a permanent record for future reference. At work: your writing should
provide your organization with a competitive edge help speed critical decision making help manage information overload
16
7
Technical Writing in Academia & in the Workplace
Professionals in engineering and technology careers spend at least 40% of their time writing. Clear and effective writing is a crucial skill needed to advance in the corporate world.
16
8
All Careers Rely on Technical Communication
16
9
Characteristics of Technical Writing
STYLE
Technical documents use a simple, concise, straightforward style. Most sentences are short. There are no surprises for the reader. Technical documents use jargon, the specialized language of a technical field.
6
10
Characteristics of Technical Writing What Is Technical Writing?
TONE
Technical documents are written to convey information, not to entertain. Technical documents have an objective or business like tone. Readers read technical documents to learn something or take action.
16 Audience Characteristics
11
Audience and Purpose
KNOWLEDGE LEVEL
What does my reader already know? Is my reader an expert, a technician, or a lay reader? What does my reader need to know? What does my reader want to know?
16 Audience Characteristics
12
Audience and Purpose
INTEREST
How strong is my reader’s interest in my topic? Are my reader’s priorities different from mine or the same as mine? Is my reader likely to agree with my point of view?
Plagiarism is the term used at school for the act of using another person’s words and ideas without giving credit. In the workplace, theft of another organization’s work often results in lost jobs, lawsuits, and ruined reputations.
16
13
Technical Research
Documenting Secondary Sources
To avoid plagiarism, document anything you use from another person’s work, including: • Borrowed phrases • Borrowed sentences • Borrowed ideas
Document ideas in: • Summaries • Paraphrases • Direct quotations
16
14
Technical Research
Documenting Secondary Sources
You can use borrowed information in your notes in these ways: • Summarize—to condense longer material,
keeping essential or main ideas and omitting nonessentials, such as examples and illustrations
• Paraphrase—to borrow or use someone else’s idea and to present it in your own words, phrases, and sentence structure
• Direct quotation—to use ideas, words, phrases, and sentences exactly as they appear in the original
16
15
Technical Research Taking Notes from Sources
Doing the right thing requires self-knowledge and courage. When individuals improve their ethical behavior, society reaps the rewards.
16
16
Why Is It Hard to Behave Ethically?
Writing activates different parts of your brain and helps you understand and retain more information. Annotating a passage means to take your own notes: • Summarize the main sections and main
ideas in your own words. • Outline the passage or draw a graphic
organizer that maps the relationship between ideas.
• Answer the questions about the text.
16 Annotate the Passage
17
Hearing what you have read and written in silence may help you retain difficult information. Try it by reading this passage several times:
Freud divided the personality into the id, the pleasure principle; the ego, the reality principle; and the superego, the morality principle.
Can you name and describe the three parts of the personality?
16 Revision: Read Your Notes Aloud
18
VALIDITY AND RELIABILITY
To maintain credibility, primary researchers look for valid and reliable data. You have valid data when you have accurately measured what you intended to measure. Reliable data means that, under similar circumstances, the results can be duplicated.
16
19
Technical Research Collecting Primary Data
• Writing is iterative(i.e., the writer moves back and forth between predictable writing stages).
• Writing takes sufficient time to complete.
• Writing is different for everyone.
16 4 A Process for Technical Writing
20
The Writing Process
SHAPING AN IDEA
Strategies to help focus your idea: • Ask yourself questions to shape your idea.
What does the reader need to know? Why am I saying this?? Motivate the topic.
• Read your notes / summaries • Draw a cluster map to shape your ideas. • Develop an outline—an informal,
changeable plan for organizing main topics and subtopics.
16 4
21
The Writing Process
A Process for Technical Writing
DRAFTING
Drafting is the second stage of the writing process.
You write drafts (versions) of the document: • Introduction • Body (including subtopics) • Conclusion
16 4
22
The Writing Process
A Process for Technical Writing
REVISING
Read the draft aloud and slowly Identify changes needed to the content, organization, and readability.
Check for consistency as the document grows. Does it have logical transitions? is the flow smooth? Does it comply with the scope and goals?
Put the draft aside for a while before you revise it.
Print a copy and make notes on it.
16 4
23
The Writing Process
A Process for Technical Writing
REVISING THE CONTENT
Do I have enough or too much information for my reader? Do I need to conduct more research or remove something?
Is my information clear? Do I need to revise for clarity?
Is my introduction effective? Do I need to revise to attract my readers’ attention?
Is my purpose clear? Do I need to add a sentence that explains the purpose?
Do the details logically support my purpose?
16 4
24
The Writing Process
A Process for Technical Writing
REVISING THE ORGANIZATION
Is the information in the best logical order for my reader? Do I need to move paragraphs or sections? Are my paragraphs and sections unified? Do I need to remove sentences that don’t fit the purpose?
Do sections and paragraphs have topic sentences? Do I need to add topic sentences?
Are transitions clear between sections and paragraphs? Do I need to add transition sentences or phrases?
Does my conclusion logically end the document?
16 4
25
The Writing Process
A Process for Technical Writing
REVISING FOR READABILITY
Does my writing flow from one sentence and paragraph to the next?
Are sentences varied by length and type? Would my sentences be more interesting if I combined them?
Have I selected the best words? Do I need to replace overused words? Do I need to define words?
16 4
26
The Writing Process
A Process for Technical Writing
COPYEDITING
Copyediting a document is proofreading it to polish it.
Check for spelling, word choice, grammar, accuracy, and consistency.
Verify the documentation of sources (references, labels,...)
Ask yourself if the document looks professional: • Is the formatting rule-compliant?
16 4
27
The Writing Process
A Process for Technical Writing
PUBLISHING
Publishing means sending your document to the person who requested it.
In this final stage, make sure the document: • Looks professional • Is ready on time • Is presented in the form your reader needs • Uses sources correctly
16 4
28
The Writing Process
A Process for Technical Writing
BE A TEAM PLAYER!
• Converge knowledge, talents, different
perspectives and viewpoints • Essential for career development • Avoid / identify / prevent abuse. Every team
member should bear a share of responsibility.
16 4
29
Writing Collaboratively The Writing Process
WORDS OF CAUTION about teamwork!
• Some people do not enjoy working in a group. • Can include conflict. • Can take longer than working alone. • Can take away personal motivation. • Can lead to unequal workloads. • Can produce fragmented writing.
16 4
30
Writing Collaboratively The Writing Process
TEAMWORK REQUIRES ORGANIZATION
• Different people write different stages. • Groups divide research tasks and come
together to write one document. • Eventually: you are going to produce a single
document graded for both of you!
16 4
31
Writing Collaboratively The Writing Process
USE POSITIVE WORK HABITS
• Do your share of the work. • Come prepared to each meeting. • Be interested in the project. • Be on time to meetings. • Not take criticism personally.
16 4
32
Writing Collaboratively The Writing Process
As a writer, you must help readers interpret graphics quickly and easily.
Keep graphics neat and simple.
Integrate graphics with text: • Refer to the graphic in the text before the graphic appears. • Explain the significance of the graphic. • Give each graphic a specific title and a caption
Give credit for borrowed graphics—put Source below the graphic and include the reference.
16 6 Designing Graphics
33
Document Design and Graphics
Color makes a document attractive and emphasizes or clarifies important points.
Consistent colors help indicate the organization.
Avoid overusing color.
16 6 Use Color Effectively
34
Document Design and Graphics
Tables are used to present words or numbers that can be organized into categories of columns and rows. Types of tables include the: • Informal table—rows and columns without
lines or column headings • Formal table—lots of numerical data; lines and
column headings make the numbers easier to understand
• Verbal table—also called a chart; a formal table with words instead of numbers
16 6
35
Constructing Tables Document Design and Graphics
A graph is a visual that shows the relationships between numerical data. Four types of graphs are the: • Bar graph (and multiple bar graph) • Line graph (and multiple line graph) • Pictograph • Pie graph
16 6
36
Constructing Graphs Document Design and Graphics
BAR GRAPH
Uses a horizontal (x) and vertical (y) axis to compare numerical data presented in rectangular bars
16 6
37
Constructing Graphs Document Design and Graphics
Source: http://www.phpclasses.org
LINE GRAPH
Use a line graph to follow a trend over time. This example is a multiple line graph.
16 6
38
Constructing Graphs Document Design and Graphics
Source: http://nces.ed.gov
PICTOGRAPH
A bar chart that represents data in pictures instead of bars.
16 6
39
Constructing Graphs Document Design and Graphics
Source: http://alex.state.al.us
PIE GRAPH
Circular graphic that shows how the parts relate to the whole.
16 6
40
Constructing Graphs Document Design and Graphics
Source: http://approximatrix.com
A chart is a drawing with boxes, words, and lines to show a process or organizational structure. Examples: • Flowchart • Decision flowchart • Organizational chart • Gantt chart
A diagram or drawing shows how something looks or how it operates.
16 6
41
Constructing Charts, Diagrams, and Pictures Document Design and Graphics
FLOWCHART
Lines and arrows show a process or series of steps.
16 6
42
Document Design and Graphics
Source: Technical Writing For Success, 6
Constructing Charts, Diagrams, and Pictures
Energy
Fat
Sugar
Starches
Glucose
DECISION FLOWCHART
Special flowchart that uses symbols to indicate critical parts of making a decision.
16 6
43
Document Design and Graphics
Source: http://fishbowl.pastiche.org
Constructing Charts, Diagrams, and Pictures
ORGANIZATIONAL CHART
Boxes, words, and lines that show how an organization is structured.
16
44
Document Design and Graphics
Source: http://www.gtairport.com
Constructing Charts, Diagrams, and Pictures
GANTT CHART
Bar chart used to schedule major tasks of a complex project. Bars depict the length of time to complete each task.
16
45
Document Design and Graphics
Source: http://www.cuttingedgepr.com
Constructing Charts, Diagrams, and Pictures
DIAGRAM
Line drawing with call outs that label specific parts of the diagram.
46 Source: http://www.nhtsa.dot.gov
Constructing Charts, Diagrams, and Pictures
A summary is a condensed version of a document.
Abstracts are more condensed
Readers who need the big picture may read only the summary or abstract.
16 Summaries and Abstracts: why?
47
Summaries: include only details that are especially important and major results
For abstracts, include only the most important general ideas.
Be concise. Reduce the original document to the main idea in a few sentences.
16
48
How Much Detail?
does not include a general background.
includes the key statements from the body of the report.
Most readers will decide from the abstract whether to spend time reading the rest
Hence, it is important that the abstract is interesting, concise and informative.
16
49
Abstract
avoid using references, acronyms, abbreviations or jargon specific to the subject area.
Is not an introduction to the topic or the report.
Do not write introductory explanations of basic concepts
16
50
Abstract
give a high-level presentation of the subject area studied,
reason about the importance and why it is an
interesting area worthy to be studied,
present a high-level description of the approach, and
summarize the contributions.
16
51
Abstract
A typical abstract is about 250–500 words. This is not more than 10–20 sentences
choose your words very carefully statements; the phrasing should be concentrated and compact.
The abstract should be the very last thing, that you write.
16
52
Abstract
how do you present the implementation in a way which convinces the reader that it is correct? One thing to rule out immediately is to simply list the code, and expect the reader to verify that it is correct Instead, you have to demonstrate to the reader that you have used good software development practice, and show the steps in the process of developing the implementation.
16 Including technical implementations
53
16 Including Technical jargon
54
Example: including code: Show the algorithm in pseudo-code
Explain relevant parts of the pseudo-code.
Show a graphical representation of the code
using, for example, flowcharts
Discuss this graphical representation in the text
to convince the reader (AND yourself) of your
understanding
16 Including Technical jargon
55
Finally, you can present relevant parts of the code, i.e. those parts that contain the key features of the implementation to demonstrate how particular implementation problems were solved..
16 Including Technical jargon
56
Where to put code: Most of the code you write should be placed as an appendix. Code sections that are included in the text should be only a few lines long
16 Conclusion
57
Most importantly: it must refer back to the aim and objectives. For example, if you have stated a specific hypothesis, the conclusion section of your report should discuss whether this hypothesis still holds
16 Conclusion
58
Was the hypothesis supported by your experiments or investigation, or does the outcome show that the hypothesis no longer holds? ?? ?? ?? Not good for a thesis!!
16 Report Writing: Language
59
Adjust your language: style, structure and length of sentences, vocabulary... Keep the goal in mind: communicate so that the reader understands your message without confusion.
16 Composition Writing: Style
60
Concise. Delete unnecessary redundancy in your report – omit needless words, phrases and paragraphs. ● Focused. Only include things that are explicitly related to your project, and which are necessary in order to understand and evaluate your work. ● Clear. Avoid unnecessarily complicated terminology, and write at a level you are comfortable with.
16 Organization
61
COMPLY WITH THE SCHOOL TEMPLATE
Covered (in, with, by, of) ? The computer was covered with dust. There is an exception (for, from, of, to, in )?? to every rule. Signal failed (to, at, on, of, ..) in reaching its destination
Prepositions
62
Common Mistakes
Process variables depend (of, upon, on, in) upon/on system variables Our method is different (than, to, of, ..) from theirs Their work is divided (on, upon, among, between..) into two parts This shield will guard my system (from, of, upon,…) against sudden changes
Prepositions
63
Common Mistakes
In this thesis we are interested (to, for, in..) in the primary effects of speed. We will use a similar approach (to, with) theirs We will use an approach similar to theirs
Prepositions
64
Common Mistakes
Look after care Look for find Look into examine closely Look over examine Overlook ?? Oversee??
Prepositions
65
Common Mistakes
Look forward to hope for look forward to seeing you here Look down on degrade Look up to respect Look out for expect
Prepositions
66
Common Mistakes
This approach is the opposite (from, to, of, against) that to We prefer the simple method (on, of, to) the sophisticated one to The result of Smith[2] is related (from, with, of) ours to
Prepositions
67
Common Mistakes
In this work we succeeded (to, at, on) proving that .. in We are sure (for, in, of, on) the validity of this equation of I am spending a lot of time (in, with, into, for) studying on After repeating the experiment 3 times, we became satisfied (in, of, with, on, at) the result with
Prepositions
68
Common Mistakes
The exam prevented me to do the other homework from doing We succeeded to prove the efficiency of our method in proving This machine is capable to run non-stop for 24 hours of running The author goes on to describe his process goes on describing
Infinitive misuse
69
Common Mistakes
This equation is simple; we will use her to estimate X. I would try to utilize the system’s resources. This method’s complexity leads to several problems general rule: inanimate objects exception: names of places, organizations
gender misuse
70
Common Mistakes
We are stronger than them. they are. There are no better results than us. Come on! ours. At least say: at the time of this writing, … we have not come across results better than ours
pronoun misuse
71
Common Mistakes
First (not firstly) Secondly (not second) Thirdly ..
Ordinal adverbs
72
Common Mistakes
School of computer and communication engineer Lebanese International University
Beirut, Lebanon in partial fulfillment of the requirements for the degree of
Report: front matter
73
Actual report/thesis examples
Special dedicated to To our beloved family, lecturer, colleagues and all people
who guided and inspired us throughout our thesis
Report: front matter
74
Actual report/thesis examples
This engine utilizes certain programming lingua franca that can deal with client’s requests.
Report: terminology
75
Actual report/thesis examples
In good spirit? Or just
attempting to be cool?
Hiyye manna mojarrad web written in HTML or any other static language bal bte7tewe 3ala application
maktoube b lo8a kteer sa3be w 3al a8lab hal lo8a hiye java. a8lab l web applications byesta5dmo l applets,li
hiyye maktoube bel java, ka application embedded inside their web.
Report: Cool
76
Actual report/thesis examples
Importance of electronic healthcare management applications. The need for custom that help healthcare individuals to enter and retrieve data in a user-friendly application that provides easy access. That an ABC-based application can achieve such goals. That this
project implements a clinical hc mgt system with support for growth charts, patient tracking graphs,
Report: who is writing notes?
77
Actual report/thesis examples
BACKGROUND: The Health care domain is an important part of society that contains many fields from hospitals to small clinics. Both need the necessity to manage data from medical record and patient information in a simple form, fast and efficiency way. After all health care is a corporation that searches for better managing technique, by integrating the hospital work with software technologies in a sophisticated manner using Electronic Medical Record (EMR) that manages the medical record electronically, creates new patient file store information and retrieves it. This simplifies the doctor’s work in the hospital or in the clinic by using software that provides simplicity in use with friendly interface.
Report:looong makes it wrooong
78
Actual report/thesis examples
BACKGROUND: Healthcare is an important service for the well-being of every society. Hospitals and clinics, large and small, all need to manage increasingly growing volumes of medical records and patient information. Such data management is desired to be simple, fast and efficient. By incorporating software into healthcare procedures, providers can manage medical records electronically. This includes creating patient files, storing daily clinical transactions, retrieving previous data and tracking patient history. Such software would also simplify healthcare workers’ jobs. The key point is to make the software interface as user friendly as possible.
Report:looong makes it wrooong
A Correction
79
Actual report/thesis examples
According to our limited abilities and timeframe, and in order to accomplish the report in a perfect scientific way, several assumptions were taken into consideration in order to recognize an OFDM signal To simplify our problem, several assumptions for recognizing an OFDM signal were upheld
Report: Sounding Defensive?
80
Actual report/thesis examples
Two stages must be passed through before reaching the recognizer. First, spectrum sensing which is clear Two stages must be passed before reaching the recognizer. The first stage is, spectrum sensing
81
Common Mistakes
Report: Do you read out (aloud) what you wrote?
82
Actual report/thesis examples
Hence, the main goal of this thesis is to mention many algorithms, and deal with each of these methods separately. Your goal is to mention algorithms??
Report: sounding confident (a bit too much)
83
Actual report/thesis examples
Indeed, we predict that, in the near future, we will witness a replacement of single carrier modulations Are you expert enough to predict this?
2.2.1 OFDM Definition
basic definitions should move up to the introduction or down to a glossary. Otherwise, do not call it definition
Report: content organization
84
Actual report/thesis examples
Report: Tell us what you know
85
Actual report/thesis examples
This type of channel leads to Inter Symbol Interference (ISI) due to multipath. Multipath? Clarify!
Report: new terms keep coming
86
Actual report/thesis examples
Thus, two approaches are concerned to mitigate ISI effects. First one is to design optimum equalizer , but such approach face many challenges based on its complexity. What is optimum equalizer? How does it work and remove the problem?
Report: appropriate terminology
87
Actual report/thesis examples
We will try to lower the cost of the application by using the same code just changing the visual design of the application in order to expand their usage to a different health care institution from small clinic to hospitals. code reuse would allow us to expand the application usage to different health care institutions requiring their own customization.
Introduction example
88
Actual report/thesis examples
Multimedia applications formulate the new revolution in the world of modern technology which is invading every corner of people’s lives. They are slowly becoming an indispensible necessity due to the facilities they continue to offer, whether they’re on mobile phones, in automobile systems, on laptops, tablets or workstations. What is the problem? References! Or is it self-created information?
Introduction example
89
Actual report/thesis examples
Such need comes from the fact that video applications are now present in almost every aspect of our lives; whether it’s in TV broadcasting, visual conferencing, mobile video calls, visual presentations or any other aspect. Who is “us”? Statement is too strong These are communication media and platforms – not aspects of life
Introduction example
90
Actual report/thesis examples
Hence, the vital necessity for video editing software that provides all desirable features for end users. Sudden jump into editing. Why? What are features? Which ones are desirable? Are there undesirable ones?
Report: sudden figures
91
Actual report/thesis examples
-… Signal How was this created? If copied, state source!
References
92
Technical Writing for Success © South-Western Cengage Learning Common mistakes in English – Fitikides – Pearson/ Longman
Actual report/thesis examples