Technical Writing for Computer Science

Lecture 1
Prof. Dr. Ahmed Elngar Prof. Dr. Mohamed Kayed
Associate Professor Professor
Head of Computer Science Department Dean of Faculty of Computers and Artificial
Faculty of Computers and Artificial Intelligence,
Intelligence, Beni-Suef University,
Beni-Suef University, Egypt
Egypt
 Course Syllabus
2

Table of Contents:

1. Introduction to Technical Report Writing

2. Characteristics of Effective Technical Writing
3. Crafting an Effective Cover Letter and Resume
4. Common Document Types
5. Algorithms
6. Oral and Visual Presentations
 Introduction
3

 Report writing is an essential skill for Computer Science students. Therefore,

this course provides guidelines to students for writing technical reports (for
example on experiments, and final-year projects).

 Computer Science reports usually present results, analyze data, and make
recommendations in a logical, precise, and accessible manner.
 Report writing is a requirement for:
4

• Academic writing: it helps you as a student or a researcher to present your

outcomes in a very precise way.

• Professional writing: it helps you as an employee or a manager to

communicate a message that shall influence actions and enrich capabilities
required in your career.
 Defining “Soft Skills”
5

Soft skills (or employability skills) can best be defined as skills

that allow students to become more effective learners and
workers. They can include:
◼ Communication Skills
◼ Time Management
◼ Organizational Skills
◼ Analytical, Problem Solving, And Reflective
◼ Thinking
 Communication Skills
6

These skills can include:

◼ Listening, Speaking
◼ Reading, Writing,
◼ Non Verbal Language
◼ Presentation Skills
◼ Documentation
◼ Teamwork
◼ Customer Service
◼ Professional Behavior
 Why Do We Care?
7

◼ These skills are key to succeeding

◼ Many students have no idea how to function in the real
world
◼ Many students mistakenly believe that technical skills
are the only skills that are important
◼ It makes life in the classroom more civilized, and you
can get more of the curriculum covered!
 Writing is learned by writing
8

◼ Practice, practice, practice

◼ Choose good role models
◼ Study good examples
◼ But there are also techniques and rules to
learn
 Technical Writing: A Definition
9

 Technical writing: this is a type of writing where the

author is writing about a particular subject that requires
direction, instruction, or explanation.

 Technical Writing: Information written by some Experts for Other

experts or other Non-Experts
 Technical Writing: A Definition
10

 The focus: writing that conveys how products

(Software, Hardware, Devices, ..etc,) and services are :
 manufactured
 marketed
 managed
 delivered
 used
 Technical Writing: A Definition
11

❑If you know clearly "why" you are writing and "who"
will read your report, you have the basis for the report
design.

❑you need to analyze your audience.

 Audiences Analysis
12

Three broad categories of audiences for a technical report

can usually be identified from the beginning:

❖ Technical
❖ Non-Technical
❖ Mixed
 Technical Audiences
13

❖ Technical Audiences are made up of people in the same field as yours. They
are the most obvious audience. They are people such as other Computer
Scientists, and technicians.

❖ They may be people you know within your own organization, or they may
work outside.

❖ Their interests may include other things as well, but it is almost certain that
they will havean interest in the subject of your report.
 Non-Technical Audiences
14

❖ Non-Technical Audiences may include, for example, citizen advisory

boards, financial experts, legal or administrative readers, and many others.

❖ Their needs will be quite different from your "technical" readers. As they
read your report, they are looking for certain things that, as a technical
writer, you need to provide.
 Mixed Audiences
15

Mixed Audiences are the most common audiences including both technical and
non-technical readers. Such audiences are more difficult to write for, but there are
several principles of report design that, if followed, will provide each reader with
the information he or she needs to use your report efficiently.

An example of this category is an engineer with financial experts.

 To Overcoming
18

Overcoming this natural reaction is a challenge,

but you can make it easier for them by designing your report
properly.

So, the Principles of good report design are mainly covered

later in this course.
 Solutions
19

❖ One of your early tasks as a report writer is to identify and analyze

your audiences.
❖ You want to know things about them such as:

✓ What their technical background is,

✓ What their function in the
organization is,
✓ What their interests are,
✓ what level of detail do they need
from your report?
 You need to know
20

❑Your Audience(s), no matter what their background,

training, interest, or position of authority, all have two
things in common:
• what your idea will cost?
• How long it takes to accomplish?

❑ If your report doesn’t answer these two questions, it is dead on arrival.

 Report Purposes
21

Every report has a purpose. Some common purposes are:

❖ To convince the reader of something. For example:
• to convince a government agency of the effect of a particular
course of action
• to convince a client that your solution will fulfill their needs.
• to convince the public that a proposed project will bring
benefits.
 Report Purposes
22

❖ To encourage the reader to do something. For example:

• to encourage a government or council to adopt a particular
course of action.
• to encourage a client to choose one design over another.
• to encourage an organization to partner with your company
on a project.
 Report Purposes
25

The general rule is to begin writing the sections of the report

as soon as possible.
• The table of contents should be drafted very early in the process of
writing the report since the table of contents provides a good overview
of the entire document, and
• While the report is being written, provide an indication of which

sections still need to be done.

 Getting Started
26

To create a useful report, you need to express the purpose of the report and
identify the audience for it. You need to define the following items:
✓ Define the purpose of the report and the key information it needs to
convey
✓ Define the audience and their level of technical understanding.
✓ Determine the level of detail necessary for the report
✓ Organize the data.
✓ Work with a team of authors
✓ Meet deadlines
 When You Work with a Team
27

When a document is a group effort,

❑ First; assign a task for each team member.
❑ Then, let each team member know the level of detail
required, the audience, and the deadlines. Everyone in the
team knows how their section fits into the whole document.
Since team members often have other responsibilities and
busy schedules,
 When You Work with a Team
28

When a document is a group effort,

❑ Follow up with each author to ensure that the commitment is being
met and whether any problems have occurred.
❑ Finally, you must select one of the team to be an editor who can
greatly enhance the final document.
❑ The editor’s role is to ensure a single, coherent writing style,
eliminate redundancies or contradictions, and maintain consistent use
of terminology.
29
 Deadline
30

❑ Deadlines should be clear, and team members should commit to

them in writing.
❑ Managing the document is a project management task that requires
frequent contact with all members.
❑ One missed deadline can cause an avalanche of missed deadlines.
❑ Therefore, it is important to be aware of potential problems before
they occur.
 Deadline
31

❑ If possible, it is always best to plan for some leeway in the

schedule so that late members do not affect the quality of the
project.
❑ Remember to allow adequate time for the editor as well as for
making copies.
❑ Tools such as Microsoft Project are helpful for monitoring
progress.
 Examples
32

 Letters : to sell, complain, hire, fire……

 Reports : to report on job-related travel or incidents, the progress of ongoing
projects and to document meetings.
 Proposals : to highlight problems, suggest solutions, and recommend action.
 Memos and e-mail : to set meeting agendas , ask and answer questions.
 Brochures : to sell and inform using 6 to 8 panel foldouts.
 Newsletters : to report activities to both employees and stakeholders.
 Examples
33

 Fliers : to sell and inform, using brief, single-sided

documents.
 Resumes : to help you find a job.
 Web-sites : to sell and inform, using multi-screened,
internet-based, hypertext-linked communication.
 User manuals : to explain the steps in a procedure
 Technical descriptions : to explain the parts of a
mechanism, tool, piece of equipment, or product.
 How to be a good writer
34

◼ You must be reasonably methodical.

◼ Be objective.
◼ As a professional, Keep in mind that most of what you
do will eventually have to be presented in writing.
◼ Remind yourself frequently that clarity is your most
importance attribute.
◼ Understand that writing is something that can be
learned.
 How to be a good writer
35

◼ We can summed up the way to be successful

with three imperatives:

1) Know your reader,

2) Know your objective,
3) Be simple, direct, and concise.
 Technical writing possibilities
36

 A bank trust officer to write 20-30 pages proposal

about the bank services to potential clients.
 A customer who writes a letter of complaint about a 5
day delayed shipment that arrived broken and cost
more than the agreed upon price
 A webmaster creating a corporate web-site with online
help screen to give the clients information about your
locations, pricing, products and services.
 Technical writing possibilities
37

 As an entrepreneur opening your own company,

you need to write fliers, brochures, or sales letters
to market your company.
 If you have just graduated from college or have
just been laid off, you need to write a resume and
a letter of application to get a job, explaining
what assets you will bring to their company.
 Technical writing possibilities
38

 A computer information systems employee who needs to answer a

client’s questions and follow up with a one page e-mail
documenting the problem and response.

 A technical writer working in engineering biomedical equipment

manufacturing, automotive industry, computer software
development…etc, who writes user manuals for building a piece
of equipment performing preventative maintenance or for
shipping and handling procedures.
 Thanks and Acknowledgement
39

Thank you