CHAPTER 1 An Overview of Technical Writing

TEXT BOOK:Reporting Technical InformationOxford University Press, 2002

Faculty of Computer

& Information Systems

Information Systems Department

2

Why Technical Report Writing

Writing your C.V.

Acquiring a job

Documenting your work

3

Your C.V.

Mohammad Ali Omar6 Mohammad Ragab St, Egypt.

E-mail : Eng.MAO575@hotmail.com

Mobile : 010 2244066

OBJECTIVEOBJECTIVE

I seek a challenging position with a reputable company which deserve my experience in the field of information

technology.

graduation Year : 2007

……

4

Your C.V.

Mohammad Ali Omar

Address :6 Mohammad Ragab St, From Sahl Hamza St, Fysal, Giza, Egypt.

E-mail : mal@menanet.net

Mobile : +2 010 2244066OBJECTIVEOBJECTIVE

Looking for a chance for working in your company, In the field of information Technology where my skills and knowledge can be utilized and developed

…..

5

Acquiring a job

Simply : How to sell you self

Writing good reports imply excellent presentation for selling yourself.

6

Documenting Your Work

Good programmer must write– System Analysis– System Design– User manual– Technical manual– E-mails– Memorandums– Business Plan

7

Documenting your work cont.

Best programmers w/o documenting his code– Can not enhance his work– Can not utilize his time effectively– Can not work with others– Can not improve his experience – Can not make international contacts– Can not get outsourcing contracts– Can not build up his career

8

Levels of Retaining

People retain – 20% of what you see– 30% of what they hear – 50% of what they see and hear – 80% of what they see, hear, and do simultaneously

So, you can say that I 100% Learn any thing new only if you:– Know it– see it– do it– teach it (writing)

9

Chinese Wisdom

I Read I Forget

I Write I Remember (Summaries & Mind-Maps)

I Do I Understand (Problem Solving ..)

10

Learning pyramid

Invent

Build

Analyze

Understand

Know

11

Course Objectives

After Finishing this course it’s expected to know :– What is a "Report" ?

– What is "Technical Report Writing" ?

– What is a "Presentation" ?

– How to make Composing Writing Collaboratively.

– How to write for different readers

12

Course Objectives Cont.

– How to achieve a Readable Style ?

– How to Write for International Readers ?

– How to Present Information in the way such that they will be easily understood ?

– How to Design the Document effectively in the way such that they will be easily readable ?

13

Definitions

A report is a written conveyed ( suggested ) message.

A technical report is a formal report designed to express technical information in a clear and easily accessible format.

14

Examples

Feasibility Study

“Reporting Technical Information” book

E-mail

Memorandums

15

Course Message

If you want one message to take from this course, take this: – The writing of a professional should be:

1. clear

2. complete

3. concise

4. Use suitable vocabulary

If your writing satisfies these four criteria, then it deserves to be read.

16

Clarity

Avoidance of irrelevant, meaningless jargon

Highlighting of main ideas

17

Completeness

Contain all information intended to be transmitted to the audience ,

Its contents bears upon the accomplishment of the stated purpose (s).

18

Conciseness

The report is concise enough if it can not be summarized without losing information.

19

Vocabulary

It has its own standard vocabulary

It is far from layman language

It assert s– Objectivity– Empiricism– Reliability

20

Objectivity

Reasoning is essential (rationalism )

To be free from bias or injustice

Personal emotions or feeling must be avoided

21

Empiricism

To deal with what is measurable, concrete, testable or observable

22

Reliability

Ability to provide trustworthy findings

Ability to draw upon for further work

23

The process

Writing is a process of recording data, idea,..

Technical report writing is a problem-solving (PS) process .

24

Problem solving process

A process to resolve a gap between :• A present situation• A desired situation (goal)

The path to the goal is blocked by:• Known Obstacles• Unknown Obstacles

25

PS Process Model Phases

PS process can have the following phases:– Perceiving the problem– Evaluating alternatives– Selecting solution– Implementing the solution– Reviewing the solution and final modifications

26

Technical Writing Elements

Technical writing is a problem-solving process involves :

• Technical Subject Matter• Recognition of the communication problem• Establishment of the role of

– The communicator– The purpose– The audience (s)

• Discovery of needed information and path• Information arrangement and presentation

27

Technical Writing Headings

1. The Nature of Technical Reports.

2. The Substance of Technical Reports.

3. The Attributes of Good Report Writers.

4. The Qualities of a Good Report.

28

The Nature of Technical Reports

Technical Report Writing has a significant differences from other writing due to its different (mostly formal) nature

Shortly, we will discuss the Technical Report Characteristics

29

Technical Report Characteristics

The technical report is likely to show the following:1. Its purpose should appear in the opening

paragraph(s).

2. Its contents bears upon the accomplishment of the stated purpose (s).

3. The writing is marked by a no-nonsense approach to the subject it treats.

30

Technical Report Characteristics Cont.

4. The vocabulary tends to be specialized.

5. Sentences are highly specific and fact filled

6. Graphs and tables may be used widely.

7. Signs, symbols, and formulas may pepper the prose.

8. References should appear at its end

31

Technical Report Users

Technical reports transfer among

– Superiors– Subordinates– Colleagues– Customers– ….

32

The Substance of Technical Reports.

Organizations produce technical reports for both:

1. Internal uses.

2. External uses.

33

Internal uses

Memorandums ) Memo)

Feasibility studies

Technical notes

34

External uses

Business letters and reports of many kinds that go to:– Other companies

– The government

– The users of the company's products.

35

Example of external uses

User manual

Technical manual

Offers

Books

Brochures

Leaflets

Business Plans for funds

Curriculum vita (C.V.)

36

The Attributes of Good Report Writers

To write clear and effective reports, you have to build upon the natural talents you have in communicating ideas to others.

But how can you build successfully ? What skills, characteristics, and attitude are most value to the report writer ?

37

Report Writers Should

1. Carefully arrange required info and put a plan.

2. Technical writers have to know well both: – Audience– Objectives

3. Then, adapt their style and Material according to both of them.

4. Gain a working knowledge:– Terminologies– Relationships

38

Report Writers Should Cont.

5. Be Understandable for yourself first.

(Your Capabilities)

6. Try always to be:– Clear– Objective– Simple– Direct– Concise.

7.ready to write!

39

Report Writers Should Cont.

8. Learn report types

9. Learn variations in format

10. Learn standards for abbreviations

11. Learn the rules that govern the writing of numbers

12. Learn uses of tables and graphs

40

The Qualities of a Good Report

1. Arrives by its due date.

2. Makes a good impression.

3. Has clear purpose and scope.

4. Has clear essential information.

5. Has summary or conclusions (when needed).

6. Has a good readability for all users.

41

The Qualities of a Good Report Cont.

7. Has a good design (Table of contents, headings, ...).

8. Reads coherently and cumulatively from beginning to end.

9. Answers readers' questions.

10. Conveys an overall impression of authority, thoroughness and soundness

42

Conveyed Impression

Authority >>>Power-ability - influence مرجعية

Thoroughness >> Care- تمكن

Soundness reliability – security- dependability

43

Question 1

What are the characteristics of a scientific paper?– Scientific Paper is introduced to journals or

conferences to be reviewed– Its structure include

• Title• Abstract• Introduction• Set of sections • Conclusions• Reference

44

Question 2

Assume you are about to write an approval as well as a disapproval of a scientific paper in a certain annual conference, How both can be different, Why?

45

Answer 2: Approval Approval is a kind of Good News, so, we should represent it directlydirectly and our ideas should be ordered as: 1. Subject : ABC conference congratulation

2. Body

Dear Dr. Adel,

We delightfully want to tell you about our approval of your Excellent Paper, Please visit our homepage www.ABC_Conf.com for comments of your paper & registration procedure.

Best Wishes, ABC Conference evaluation committee

46

Answer 1 Cont. : Disapproval Disapproval is a kind of Bad News so, we should represent it IndirectlyIndirectly & our ideas should be ordered as:

1. Subject : ABC conference

2. Body

Dear Dr. Adel, Thank you for delivering your paper at our conference whose topic this year is so novel thus it takes the attraction of many researchers around, since, we are only about to accept a limited number of papers, we sorrowfully can’t accept your paper at our current conference, please visit our homepage www.ABC_Conf.com for registration, hopefully, next year we can have the chance with you

Best Wishes, ABC Conference evaluation committee

47

Question 2

Mention True or False & justify your answer for each of the following statement: 1. The purpose of the scientific paper should

appear at its conclusion part2. Graphs and tables should be used widely in

scientific paper 3. The vocabulary of a scientific paper should tend

to be generalized 4. References that are used in a scientific paper

should appear directly after its abstract part5. There are no differences between abstract &

conclusion thus use either of them when writing a scientific paper

48

Answer 2

1.1. The purpose of the scientific paper should The purpose of the scientific paper should appear at its conclusion partappear at its conclusion part FalseFalse The purpose of the scientific paper should

appear at its beginning in the abstract part not at its end at the conclusion part

Back

49

Answer 2 Cont.

2.2. Graphs and tables should be used widely in Graphs and tables should be used widely in scientific paperscientific paper TrueTrue graphs and tables are considered one of the

ways that increase the clarity of any scientific discussion specially the scientific paper since it lets the paper to be easily understood

Back

50

Answer 2 Cont.

3.3. The vocabulary of a scientific paper should tend The vocabulary of a scientific paper should tend to be generalizedto be generalized FalseFalse The vocabulary of a scientific paper should tend

to be specialized since the scientific paper is a kind of argumentative writing in which the ideas is reached point by point to an important conclusion so, we have to avoid using ambiguous & general vocabularies that might have more than one meaning

Back

51

Answer 2 Cont.

4.4. References that are used in a scientific paper References that are used in a scientific paper should appear directly after its abstract partshould appear directly after its abstract part FalseFalse References that are used in a scientific should

appear directly after its conclusion part at its end NOT at its beginning

Back

52

Answer 2 Cont.5.5. There are no differences between abstract and There are no differences between abstract and

conclusion thus use either of them when you are conclusion thus use either of them when you are about to write a scientific paperabout to write a scientific paper FalseFalse

Conversely, there are many differences between abstract & Conclusions

AbstractAbstract Conclusion Conclusion

RoleRole Highlights the major points of the scientific paper

Summarizes the major point and results of the scientific paper

AimAim Enables the interested reader to decide whether the work as whole is worth reading

Enables the interested reader to be sure of what he should get from this paper since it Focuses more on the contributions of the scientific paper

PlacePlace we should place it at the beginning of the scientific paper

we should place it at the end of the scientific paper

That’s All

53

Problems

Apply the previous questions on the following technical reports– Research on specific topic– PhD Thesis – Report of Lab experiment

54