Technical Writing for Computer Science
Lecture 1
Prof. Dr. Ahmed Elngar
Associate Professor
Head of Computer Science Department
Faculty of Computers and Artificial
Intelligence,
Beni-Suef University,
Egypt
Prof. Dr. Mohamed Kayed
Professor
Dean of Faculty of Computers and Artificial
Intelligence,
Beni-Suef University,
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