Technical Report Writing

Ferid Bedru Sherif

Backend Developer
 Description

• Duration ~ 2:30 Hours

• Break - once at the first half of the session

• Purpose
• Differentiate between technical and non technical reports
• Prepare a technical document
• Present a technical document to different audiences

• Prerequisites
• None
 Agenda

01 Introduction 05 Writing

02 The Types 06 Presentation

03 Audiences 07 Q&A

04 Planning
Topic 1
Introduction
 Objective

• Be able to explain what technical report writing is

• Explain the use of technical report writing

 Topics

•
 Intro

• Communication can be of the following types

• written

• oral

• formal

• non-formal

• Technical Communication - process about communicating technical topics

 Technical Report

• report about technical subjects written in the “language of science and

technology” (special terms and phrases, display rules etc.)

• must have a high level of systematic order, inner logic, consistency etc.

• It shall bring clarity to the reader

 Benefits

• making your boss happy

• Analysis of strength of the work

• Completes the job

• No alteration unlike verbal

• Required by many standards

 Document Types

• Email

• Letter

• Technical Memorandum

• Informal Report

• Formal Report

• Paper

• Patent
Plagarisim?
 Document Produced

• Guides and User Manuals

• White Papers & Case Studies

• Executive Summaries

• Product Description

• Proposal
Summary
Topic 2
The Types
 Topics

• Software documentation

• User manuals

• Technical specifications

• Reports
 Software Documentation

• Documentation that is related to software development.

• System Requirement Specification

• System Design

• Release notes
 User Manual

• documents that provide guidance on how to use a product or service

• They usually contain information on the product's features and functions,

how to install and configure the product, and troubleshooting tips.

• They are supplemented with screenshots.

 Technical Specifications

• documents that define the requirements and constraints for a product or

service

• They usually include technical details about the product's functionality,

design, and performance.

• used to ensure that products or services meet the required standards

 Reports

• documents that present the results of research, experiments, or other

technical activities.

• usually include an introduction, methodology, results, and conclusion

sections

• used to share research findings, provide updates on projects, or provide

recommendations for future work
Topic 3
Audiences
 Know Your Audience

• understand who your audiences are

• their background

• their level of technical knowledge

• their language proficiency

• their expectations for the document

 Major Tips

• Use Clear and Concise Language

• Adapt Your Writing Style

• Provide Context

• Use Visual Aids

• Test Your Content

 Topic 4
The Process - Planning
 The steps

• Accept and analyze the task • Develop the detailed structure

• Check or create the title • Perform the final check

• Design a structure • Print copy originals or create PDF file

• Search, read and cite literature • Copy and bind the report

• Elaborate the text • Distribute the report to the defined

recipients
• Create or select figures and tables
 Task Definition

• Who has defined the task?

• Did I understand the task correctly?

• Who belongs to the target group?

• For whom do I write the report?

• Which contents shall my report contain?

 Checking or creating the title

• shall contain the main topic or the main keywords of the report, it shall be
short, precise and true.

• Explaining or additional aspects can appear in a subtitle.

• it must create interest and curiosity

• have a good speech melody

 Activity - creating a title

• Write down the main keywords which characterize your project

• connect these keywords to a title

• create several title variants by using different keywords

• select the “best” title.

 Define the structure

• designing the structure is the main step of planning

• important for the understandability and plausibility of texts

• you should always structure every text that exceeds the amount of about
one page with intermediate headings
Document Part Headings
 Structure Rules

• use consecutive Arabic numerals.

• subdivisions are also continuously numbered

• full stop between the numbers of subdivisions on different levels

 Rules of Logic

• Full stops in section numbers define the hierarchy level in the document

• Each hierarchy level consists of at least two document parts which are
logically of equal importance

• The document part heading may not be the first part of the first sentence of
the first paragraph in the appertaining text
 Formal Rules

• The declaration in lieu of an abstract, foreword/preface and table of contents

always get a document part heading, but no document part number.

• At the end of document part number and document part heading never use a
punctuation mark like period, colon, question mark, exclamation mark

• It is unusual to formulate the document part heading as a complete sentence or

as a main clause with one or more subclasses
 Layout Rules

• for table of contents, use the builtin provided by the word processor
software and make sure to use the necessary headings

• avoid capital letters in headings and table items

• for table of figures and tables, make sure to use the generator to generate
automatically
 Style Guide

• Differs based on the institution

 Topic 5
The Process - Writing
 Before you start

• When does the reader need which information?

• Does the current figure appear “out of the blue”?

• Should I pick up the structure, write an intermediate summary, or

announce the new document part from a very general point of view?

• Is the subdivision of information logical and comprehensible?

 The parts

• Front cover • list of illustrations (figures) and list of

tables
• title leaf
• list of abbreviations and symbols
• errata page(s)
• main text with essential figures,
• abstract
illustrations and tables, list of
• preface references

• table of contents • glossary

 Front Cover and Title Leaf

• front cover sheet is the title visible when the Technical Report lies on a
table as a closed book

• The title leaf is only visible after you opened the Technical Report and in
most cases after you turned a blank white sheet of paper.

• front cover sheet is a transparent sheet of plastics

• the title leaf always contains more information than the front cover sheet
e.g personnel listings
 Common Mistakes

• The name of the institution is missing on the top of the page.

• The name of the university is correctly specified, but the name of the
department and/or institute are missing.

• The title is layouted with a too small font size, while the type of report is
much larger than the title.
Identify the correct one
Alignments
Sample 1 - Thesis
Sample 2 - Report
 Checklist - Front Cover Sheet

• (Logo and) institution

• Title of the work (large!)

• Subtitle (if applicable)

• Type of report (smaller!)

• Author/s (medium)
 Checklist - Title Leaf

• (Logo and) institution: university/department/institute

• Title of the work (large!)

• Subtitle (if applicable)

• Type of report (smaller!)

• in the subject <name of the subject>

• Specification of semester or term

• supervised by : name with title

• written by : full name and identification

 Table of Content (1)

• The page numbering always begins on the first text page

• Front matter pages are pages prior to the main text part of the document

• front matter should get Roman page numbers

• In the table of contents the page number being listed is only the first page
number of any document part
 Table of Content (2)

• The page numbers are printed right-justified.

• the hierarchy level in the document all document part numbers are aligned
along a common building line.
ToC better readability - use indentations and tabs
 Toc - Spacing

• groups of document part headings can be built up by a variation of the

vertical distance between the document part headings in the table of
contents.
 Toc - Gap filling

• gap between all document part headings and the appertaining page number
should be filled with the same leading dots
 The Introduction

• located at the beginning of the text and is normally the first chapter.

• describes the starting situation at the beginning of the project, the

relevance of the project for the particular field of science, the results of the
research for the society, and other similar aspects.

• can contain a description of the project task and project target formulated
by the author

• should tie up with prior knowledge and experiences of the readers.

 The Summary

• located at the end of the text and is normally the last chapter.

• can have document part headings like: summary, summary and

conclusions, summary and evaluation etc.

• discusses the task in terms of what has been done

• describes shortly what is covered in which chapter and subchapter of the

Technical Report
 Lists

• A List of figures contains figure numbers, figure titles, and page numbers

• A List of tables contains table numbers, table titles, and also page
numbers.

• List of abbreviations contains the used abbreviations in alphabetical order

and an explanation for each of them.
 Creating tables

• The header contains the superordinated concepts (generic terms) of the

columns.

• Use small tables as much as pssobile for better visualization

Table Design - refer to your institution
 Table design - consideration

• Indentation - Texts within cells are mostly left-justified

• Shading - Use builtin feature of the word processor

• As much as possible, keep portrait orientation

• sufficient line spacing

• use border lines - specially horizontal line

 Table numbering and table headings

• cited tables must get an indication of source (citation).

 Referencing to a table

• ..., Table xx.

• …, see Table xx.

• … shows the following table.

• … shows Table xx.

Evaluation Tables
 Figures

• figure subheadings shall be placed below the figure.

• The figure label is accentuated by bold type printing.

• The figure numbers can be consecutively counted through the whole report

• They can also be a combination of the chapter number and the figure
number which is consecutively counted within the chapter
Figure - Alignment
 Reference to a figure

• …, Figure xx.

• …, see Figure xx.

• … shows the following figure.

• … shows Figure xx.

 Charts

• axes, bars, sectors etc. must be labeled unambiguously

• diagram title below the diagram with a figure label

Mind Mapping
 Literature citations

• A citation is using a statement written by another author either literally or

in one’s own words and precisely documenting the literature source from
where the statement is cited.

• they help to describe the current state-of-the-art,

• they support the author’s opinion,

• they emphasize the scientific character of the Technical Report

 Literature citations

• they exculpate the author from the responsibility for the contents of the
citation

• they point out the author’s accuracy and intellectual honesty,

• they underline the author’s authority and credibility and

• they permit that the readers can check the facts

• by studying the literature from several authors to get a higher level of

expertise in the current field of science.
 Why we cite?

• Correct literature citations emphasize the honesty of the author.

• literature citations do not express, that the author has not had own ideas

• Governed by copyright laws

Citation Styles
 IEEE Style
Material Type Works Cited
Book in print [1] B. Klaus and P. Horn, Robot Vision. Cambridge, MA: MIT Press,
1986.
Chapter in book [2] L. Stein, “Random patterns,” in Computers and You, J. S. Brake,
Ed. New York: Wiley, 1994, pp. 55-70.
eBook [3] L. Bass, P. Clements, and R. Kazman, Software Architecture in
Practice, 2nd ed. Reading, MA: Addison Wesley, 2003. [E-book]
Available: Safari e-book.
Journal article [4] J. U. Duncombe, "Infrared navigation - Part I: An assessment of
feasability," IEEE Trans. Electron. Devices, vol. ED-11, pp. 34-39,
Jan. 1959.
eJournal (from database) [5] H. K. Edwards and V. Sridhar, "Analysis of software
requirements engineering exercises in a global virtual team setup,"
Journal of Global Information Management, vol. 13, no. 2, p. 21+,
April-June 2005. [Online]. Available: Academic OneFile,
http://find.galegroup.com. [Accessed May 31, 2005].
 IEEE Style
Material Type Works Cited
eJournal (from internet) [6] A. Altun, "Understanding hypertext in the context of reading on
the web: Language learners' experience," Current Issues in
Education, vol. 6, no. 12, July 2003. [Online]. Available:
http://cie.ed.asu.edu/volume6/number12/. [Accessed Dec. 2, 2004].
Conference paper [7] L. Liu and H. Miao, "A specification based approach to testing
polymorphic attributes," in Formal Methods and Software
Engineering: Proceedings of the 6th International Conference on
Formal EngineeringMethods, ICFEM 2004, Seattle, WA, USA,
November 8-12, 2004, J. Davies, W. Schulte, M. Barnett, Eds. Berlin:
Springer, 2004. pp. 306-19.
Conference proceedings [8] T. J. van Weert and R. K. Munro, Eds., Informatics and the
Digital Society: Social, ethical and cognitive issues: IFIP
TC3/WG3.1&3.2 Open Conference on Social, Ethical and Cognitive
Issues of Informatics and ICT, July 22-26, 2002, Dortmund,
Germany. Boston: Kluwer Academic, 2003.
 IEEE Style
Material Type Works Cited
Newspaper article (from [9] J. Riley, "Call for new look at skilled migrants," The
database) Australian, p. 35, May 31, 2005. [Online]. Available: Factiva,
http://global.factiva.com. [Accessed May 31, 2005].
Technical report [10] J. H. Davis and J. R. Cogdell, “Calibration program for the
16-foot antenna,” Elect. Eng. Res. Lab., Univ. Texas,Austin,
Tech. Memo. NGL-006-69-3, Nov. 15, 1987.
Patent [11] J. P. Wilkinson, “Nonlinear resonant circuit devices,” U.S.
Patent3 624 125, July 16, 1990.
Standard [12] IEEE Criteria for Class IE Electric Systems, IEEE Standard
308, 1969.
Thesis/Dissertation [1] J. O. Williams, “Narrow-band analyzer,” Ph.D. dissertation,
Dept. Elect. Eng., Harvard Univ., Cambridge, MA, 1993.
Sample reference
 Good writing style in general texts

• Formulate short sentences.

• If possible, use only one main clause with one or two subordinate clauses
or two main clauses connected with a comma or semicolon.

• Do not use too many foreign words.

• Explain foreign words and unknown abbreviations when they occur the
first time.

• Avoid too many abbreviations.

 Good writing style in general texts

• Use introductory and connecting sentences, to guide your readers with

words.

• Use descriptive formulations, write vividly and engagingly

• passive sentences are used quite frequently

• personal pronouns like “I, we, my, our, you, etc.” are avoided

• The tense is present tense. Past tense is only used, if a previously used
part, measuring procedure or similar is described
 Understandable Writing - Readers

• general prior knowledge of the readers,

• their ability to concentrate on reading and their routine in reading,

• their motivation for or inner aversion against the topic(s) of the text,

• their command of the language in which the text is written,

• their knowledge of technical terms, and

• their expertise in the described field of knowledge.

 Understandable Writing - Text Properties

• Is the title descriptive and does it create interest?

• Is there a structure and is it logical (“backbone”)?

• Paragraph length?

• Sentence length?

• Nested sentences?

• Are unknown words explained when they are used for the first time?

• Are unknown abbreviations explained when they are used for the first
time?
 Sentence Composition Checklist (1)

• The sentences should be as short and simple as possible.

• Each new fact should preferably be described in a new sentence.

• Leaving out verbs to shorten sentences is not allowed.

• The sentences should not be longer than 25 to 30 words.

• Paragraphs should have maximum six sentences.

• Paragraphs with only one sentence should not appear too often.
 Sentence Composition Checklist (2)

• Tables and bullet lists should be used as often as appropriate.

• Compound tenses should be avoided, the simple tenses are better understandable
for most people.

• Abstract nouns (foreign words) are tiring for the readers and should therefore be
avoided.

• Meaningless phrases and filler words also appear as tiring, if they are used too
often, and should be used carefully.

• The first verb should not appear too far at the end of the sentence.
 Sentence Composition Checklist (3)

• If a word is used in an unusual meaning, please use quotation marks or

italic printing.

• Nested sentences should be avoided. Parentheses in such sentences should

be only short.

• Double negations are in most cases superfluous.

 Report Checklist - Toc

• Heading “Contents”?

• Are there page numbers? is only the first page of every document part
listed?

• Are page numbers aligned right-justified?

• Document part number, heading and page number must be identical in the
text and in the table of contents!

• Has the automatically created table of contents been updated?

 Report Checklist - Contents

• The names of sub functions must be identical in the verbal assessment, in

all descriptions in the Technical Report regarding number, name and order.

• Reduce sentences in your mind to check, whether they are logic, i e. leave
out sub clauses and ellipses. Is there a complete sentence left?
 Report Checklist - Spelling and Layout (1)

• Is the text left- and right-justified?

• Is automatic hyphenation switched on?

• Is the sign for a range of numerical values either “to” or “–”?

• No space character before full stop, colon, comma, semicolon, exclamation

mark.

• Always use a tab between bullet and list item.

• Are bullets used consistently on different hierarchy levels in lists?

 Report Checklist - Spelling and Layout (2)

• There is always a space character between physical value and physical unit.

• Before and after each mathematical operator (+, –, x, :, <, >, = etc.) there must
be one space character.

• The signs + and - are placed before the numerical value without space
character.

• All types of brackets, i. e. (...), [...], /.../, {...} and <...> enclose the text
directly without space characters. The same is true for quotes “” and ‘’.
 Report Checklist - figures and tables

• Figures have a figure subheading, tables a table heading.

• Avoid too thin lines because of problems when copying.

• Figure and table titles always begin with a capital letter.

• Adjectives in tables and lists of requirements should consistently begin

with small letters

• Is it automatically generated? is it updated?

 Report Checklist - Line Breaks

• Are the results of the automatic hyphenation correct?

• If there are too wide gaps between words (when text is left- and right-
justified) or if the line width differs too much (when text is left-justified)
insert hyphenation proposals.

• If possible, after hyphenation there should not be one syllable alone in a

line.
 Report Checklist - Page Breaks

• Document part heading alone at the bottom of a page and appertaining text
on the next page is a no-go!

• One line standing alone at the end or beginning of a page should be

avoided.

• Landscape format must be readable, if you turn the page by 90° clockwise
Proof reading
Discussion Topic
Topic 6
Presentation
 The process

• Phase 1: In your mind, try to get as much distance from your report as
possible.

• Phase 2: Slip into the position of your audience including professor(s),

your boss and other experts and try to anticipate their existing knowledge,
attitude and expectations.

• Phase 3: You try to meet these expectations of your audience as well and
complete as possible.
Plan your presentation
Time Consumption
 Presentation Framework

• What do I talk about? (topic)

• What shall be the title of my lecture?

• What kind of lecture will I present? (presentation type)

• Who will listen to me? (audience, target group)

• What is the occasion to present my lecture?

• What do I want to achieve with my lecture? (presentation targets)

• Why do I want to achieve that? (purpose)

• Where do I present my lecture? (surroundings, room)

Use the 3 steps approach
Presentation Design
Topic 7
Q&A
 Q&A

• Demo for documents