Bài giảng Technical writing and presentation

ion word what, why, when, where, how or if/whether when the corresponding direct question begins by a verb. ”First we should study what is the relationship between X and Y .” ”The main problem is whether X can be applied in Z.” • The word order is direct! • No auxiliary word do • No comma! • No question mark © SoICT 2020 Technical Writing and Presentation 62 Punctuation
Goal: to make the text clearer.
The English punctuation rules do not always coincide with the rules of your mother tongue.
Usually you manage with just two marks: full-stop and comma!
The basic rules for other marks are: • Use colon ’:’ only when needed. • Avoid semicolon ’;’ and dash ’–’. • Avoid unnecessary parantheses ’(’...’)’. © SoICT 2020 Technical Writing and Presentation 63 Comma is used 1. To separate introductory phrases and conjunctions (however, thus, similarly, etc.) ”Despite the high time complexity, X is often used...” 2. When the sentence begins with a dependent clause. ”Since x is a statistic, it is also a random variable.” 3. When a non-restrcitive relative clause is embedded into an independent clause or ends a sentence. ”X, which is responsible for data preprocessing, initializes Y .” 4. When two phrases with the same meaning are used side by side. ”One of the most useful statistics is x, the sample mean.” 5. When the sentence begins by an infinitive structure ”To find the lower bound for the confidence interval, we isolate...” 6. To separate items in a list of three or more items. 7. To avoid ambiguity. ”Instead of hundreds, thousands rows of data is required” © SoICT 2020 Technical Writing and Presentation 64 61 62 63 64 Technical Writing and Presentation 2016 17 No comma is used
When an independent clause is followed by a restrictive relative clause or is embedded with a restrictive rel. clause (especially before that). Exception: ”It must be remembered, however, that...”
Between two independent clauses (in British English).
Before an indirect question.
When you begin by a prepositional phrase expressing the place.
”In this section we discuss...” ”In Chapter 3 we defined...” © SoICT 2020 Technical Writing and Presentation 65 65 Technical Writing and Presentation 2016 1 Technical Writing and Presentation Writing scientific text in computer science SOICT - 2020 TRƯỜNG ĐẠI HỌC BÁCH KHOA HÀ NỘI HANOI UNIVERSITY OF SCIENCE AND TECHNOLOGY Scientific Writing for Computer Science 1. How to write scientific texts in computer science? 2. How to write in English? 3. How to write a technical report / thesis? © SoICT 2020 Technical Writing and Presentation 2 Contents
General style
References and citations
Acknowledgements
Formatting
Use of tables, figures, and similar elements.
Mathematics © SoICT 2020 Technical Writing and Presentation 3 General style
What is style?
Scientific writing style © SoICT 2020 Technical Writing and Presentation 4 1 2 3 4 Technical Writing and Presentation 2016 2 Genre (style)
The manner of expression is the writing style: how well you communicate with likely readers.
Scientific writing must be plain and straightforward but not dull. It can have style.
Good style makes your writing easy to understand. It can persuade readers that work is of value. © SoICT 2020 Technical Writing and Presentation 5 Scientific writing style
Fundamental aims of science writing: to be exact, clear, and compact.
Compact is usually clear!
Other desirable properties: smooth and objective © SoICT 2017 Nhập môn CNTT&TT 6 Exact
Word choice
Avoid vague expressions which are typical for the spoken language
Make clear what the pronouns refer to
Avoid ambiguity
Avoid illogical comparisons
Correct grammar © SoICT 2017 Nhập môn CNTT&TT 7 Avoid ambiguity
Example An inverted list for a given term is a sequence of pairs, where the first element in each pair is a document identifier and the second is the frequency of the term in the document to which the identifier corresponds. An inverted list for a term t is a sequence of pairs of the form (d, f) where each d is a document identifier and f is the frequency of t in d
Many terms have well-defined mathematical meanings and are confusing if used in another way.
For example,
Formula, expression, equation
Average, mean
Subset, proper subset, strict subset. © SoICT 2020 Technical Writing and Presentation 8 5 6 7 8 Technical Writing and Presentation 2016 3 Use Words Efficiently
Never use two words when one word will do. Example 1: The relationship between the nature of salt water to fresh water in the Edgartown Great Pond that fluctuates often is extremely important to everyone including scientists, residents, and environmentalists on Martha’s Vineyard. Example 2: The fluctuating salinity of EGP concerns many environmentalists, scientists, and residents. © SoICT 2020 Technical Writing and Presentation 9 Clear
Use illustrative titles which describe the essential in a chapter or a section.
Write a brief introductory paragraph in the beginning of each chapter or section with subsections.
Divide the text logically into sentences and paragraphs.
Place the adjective or the adverb as close as possible to the word it modifies.
Avoid scientific jargon = continuous use of technical vocabulary when it is not relevant.
Write numbers as digits when they refer to sizes or exact measurements.
Use punctuation to support meaning. © SoICT 2017 Nhập môn CNTT&TT 10 Avoid jargon
Jargon: a vocabulary particular to a place of work (abbreviations, slang)
Audience familiarity with the topic determines appropriate use of jargon  For the first year, the links with SDPC and the HAC were not connected, and all required OCS input data were artificially loaded. Thus CATCH22 and MERWIN were not available. Because some of the links in the computer system were not connected the first year, we could not run all the software codes. © SoICT 2020 Technical Writing and Presentation 11 Define the Unfamiliar • If you must abbreviate, define the term in its first occurrence, and put abbreviations in parentheses Example: Edgartown Great Pond (EGP) is a vital body of water. Unfortunately, due to an unpredictable influx of saltwater, the delicate ecosystem is in danger of destabilizing. • Italicize first occurrence of unfamiliar terms and define them right away Example Retina is a light-sensitive tissue, found at the back of the eye, that converts light impulses to nerve impulses. © SoICT 2020 Technical Writing and Presentation 12 9 10 11 12 Technical Writing and Presentation 2016 4 Compact
Say only what needs to be said!
Short words and short sentences are always easier to comprehend
Weed out too detailed descriptions.
Don’t describe irrelevant or trivial observations
Avoid wordiness, Use no more words than are necessary. Redundant words and phrases should be omitted.
Avoid too long sentences and paragraphs © SoICT 2017 Nhập môn CNTT&TT 13 Smooth
Verbs: Stay within the chosen tense! No unnecessary shifts in verb tense within – the same paragraph – in adjacent paragraphs
Use verbs rather than their noun equivalents
Prefer active to passive voice
Avoid long noun strings!
Each pronoun should agree with the referant in number and gender.
Transitional words help to maintain the flow of thought © SoICT 2017 Nhập môn CNTT&TT 14 Smooth
Notice: some transitional words (while, since) can be used in several meanings → limit their use to their temporal meaning!
Use abbreviations sparingly, especially the abbreviations which you define yourself for technical terms.
Do not use emphasis (italics) when it is not needed. Use syntax to provide emphasis.
Metaphors can sometimes help to simplify complex ideas. However, – Avoid overuse metaphors and cliches © SoICT 2017 Nhập môn CNTT&TT 15 Active voice
Use direct statements and expressions involving “we” or “I”—that is, the active voice—to make reading more pleasant and to help distinguish new results from old. © SoICT 2020 Technical Writing and Presentation 16 13 14 15 16 Technical Writing and Presentation 2016 5 Example: active voice vs passive voice The results show that, for the given data, less memory is likely to be required by the new structure, depending on the magnitude of the numbers to be stored and the access pattern. The results show that less memory was required by the new structure. Whether this result holds for other data sets will depend on the magnitude of the numbers and the access pattern, but we expect that the new structure will usually require less memory than the old. © SoICT 2020 Technical Writing and Presentation 17 References and Citations
References and citations
explain the relationship of your new work to existing works.
how your work was built on previous knowledge and how it differs from contributions in other paper
References must be in standardized format © SoICT 2020 Technical Writing and Presentation 18 Purposes of references
Demonstrate that your work is new
Demonstrate your knowledge of the research area
Help the reader to judge whether your statements are reliable.
Pointers to background reading. © SoICT 2020 Technical Writing and Presentation 19 An appropriate reference is
Relevant
up-to-date
reasonably accessible
Refer to the original paper
well-written material
book, conference paper, journal article in preference to a workshop paper
workshop paper in preference to a manuscript
formally published documents rather than Web pages
Avoid reference to private communications and information provided in seminars or talks
Don’t cite to support common knowledge. © SoICT 2020 Technical Writing and Presentation 20 17 18 19 20 Technical Writing and Presentation 2016 6 Examples
Refer to a result in an inaccessible paper, do not refer to it directly: According to Kelly (1959; as quoted by Dawson 1981), stable graphs are closed
When you use results from other papers, be sure to show the relationship to your own work:
Marsden [16] has used an approach in whichN Other work (Marsden 1991) has used an approach in whichN © SoICT 2020 Technical Writing and Presentation 21 Citations
Citations should be punctuated
Never treat a bracketed expression, whether a citation or otherwise, as a word. In [2] such cases are shown to be rare. Such cases have been shown to be rare [2]. © SoICT 2020 Technical Writing and Presentation 22 • The cite should be close to the material it relates to The original algorithm has asymptotic cost O(n2) but low memory usage, so it is not entirely superseded by Ahlberg’s approach, which although of cost O(n log n) requires a large in-memory array (Ahlberg 1996; Keele 1989) The original algorithm has asymptotic cost O(n2) but low memory usage (Keele 1989). Thus it is not entirely superseded by Ahlberg’s approach (Ahlberg 1996), which, although of cost O(n log n), requires a large in-memory array © SoICT 2020 Technical Writing and Presentation 23 Citations Acknowledgements
Should thank everyone who made a contribution, whether advice, proofreading, coding, or whatever
Two common forms of acknowledgement
list the people who have helped
explain each person’s contribution
Write “I am grateful to” , “I thank” or “Thanks to” instead of “I would like to thank” or “I wish to thank” © SoICT 2020 Technical Writing and Presentation 24 21 22 23 24 Technical Writing and Presentation 2016 7 Formatting
Fonts
Indentation
Layout
Headings
Numbering © SoICT 2020 Technical Writing and Presentation 25 Fonts
Standard choices: Times New Roman, Cambria.
Three fonts for computing and mathematical writing : plain, italic, bold
Underlining is used for emphasis.
© SoICT 2020 Technical Writing and Presentation 26 Indentation
Indentation is used to indicate the start of a new paragraph
Use right-justified as well as left-justified
Pages should be numbered © SoICT 2020 Technical Writing and Presentation 27 Layout
The appearance of a report is no less important than its content.
An attractive, clearly organised report stands a better chance of being read.
Use a standard, 12pt, font, such as Times New Roman, for the main text.
Use different font sizes, bold, italic and underline where appropriate but not to excess.
Too many changes of type style can look very fussy. © SoICT 2017 Nhập môn CNTT&TT 28 25 26 27 28 Technical Writing and Presentation 2016 8 Headings
Use heading and sub-headings to break up the text and to guide the reader.
They should be based on the logical sequence which you identified at the planning stage but
With enough sub-headings to break up the material into manageable chunks. © SoICT 2017 Nhập môn CNTT&TT 29 Numbering
The use of numbering and type size and style can clarify the structure as follows; © SoICT 2017 Nhập môn CNTT&TT 30 Use of tables, figures, and similar elements
Figures and tables
Diagrams
Graphs
Lists
Algorithms
Examples and definitions
Equations © SoICT 2020 Technical Writing and Presentation 31 Figures and tables
General rules
Vector graphics
Captions
Expressions © SoICT 2020 Technical Writing and Presentation 32 29 30 31 32 Technical Writing and Presentation 2016 9 General rules
Figures illustrate the models or the results, and tables give summaries.
Two rules for displaying figures and tables 1. All figures and tables must be referred in the text. 2. There is no sense to express trivial things as a figure or a table
If there is no need to refer to a figure/table in the text, the figure/table is probably not needed!
Avoid repeating the same data in several places.
Discuss only the most important items of the table in the text.
A figure should be easy to understand..
If two tables/figures should be compared, position them next to each other. © SoICT 2020 Technical Writing and Presentation 33 Vector graphics
Use vector graphics, not raster graphic (bitmaps)! There is a big difference in quality: © SoICT 2020 Technical Writing and Presentation 34 Tables
Is a table the best way to present your information?
Consider graphs, bar charts or pie charts.
Dependent tables (small) can be placed within the text, even as part of a sentence.
Independent tables (larger) are separated from the text with table numbers and captions. Position them as close as possible to the text reference.
Complicated tables should go in an appendix. © SoICT 2017 Nhập môn CNTT&TT 35 Captions
Each table or figure should be understandable by its own. Give a brief but clear explanation or a title in the caption.
Explain all special abbreviations, symbols, special use of underlinings, dashes, parantehses, etc.
Use the same style in all tables.
If you copy (draw again) a table or a figure from some other source, then give a reference to the original source in the end of caption. © SoICT 2020 Technical Writing and Presentation 36 33 34 35 36 Technical Writing and Presentation 2016 10 Expressions
When you refer to figures and tables you can use the following expressions:
The results are summarized/reported in Table 1
The results are represented in
Figure 2 illustrates
In the Figure we observe
The model is given in Figure 7
etc. © SoICT 2020 Technical Writing and Presentation 37 Diagrams
Keep them simple.
Draw them specifically for the report.
Put small diagrams after the text reference and as close as possible to it.
Think about where to place large diagrams. © SoICT 2017 Nhập môn CNTT&TT 38 Graphs
Graphs must be used particularly when trends are shown or series of data are compared.
Graphs containing data that need to be compared must be combined in the same figure so that the reader can make a direct comparison between the values.
The quantity of information in one graph must be limited so that the different symbols can be clearly distinguished.
The axes of a graph must be named in words, in conjunction with units. © SoICT 2017 Nhập môn CNTT&TT 39 Lists
Lists are not separate objects, and they are introduced in the text.
Use list only when they are necessary! E.g. ”The main criteria of X are (the following):” – Criterion 1 – Criterion 2 – ... Or ”The method consists of five steps:” + a list
If you list only a couple of items, you can usually write them without a list. Use lists when the clarify things! © SoICT 2020 Technical Writing and Presentation 40 37 38 39 40 Technical Writing and Presentation 2016 11 Algorithms
Give only the main algorithms in the text, and in an appropriate abstraction level (pseudocode)
Fix the pseudocode notation and use it systematically
Simple methods can be described by a numerated list of steps
Logical and set operations are often useful when you describe algorithms in an abstract level
E.g. for all xi ∈ X, T = T ∪ {pi}, find such S ⊆ T that q(S),...
If you writer longer algorithms, insert them into a figure or an environment of their own.” © SoICT 2020 Technical Writing and Presentation 41 Example of Algorithm © SoICT 2020 Technical Writing and Presentation 42 Definitions
A good definition
explains the defined concept.
is not a circular argument (where x is defined by y and y by x).
is not expressed by negative terms, if possible.
doesn’t contain unclear, vague, or descriptive language •
defines only what is needed © SoICT 2020 Technical Writing and Presentation 43 Expressions for referring to a definition
The definition of ... is the following:
The definition of ... is as follows:
Formally, we define N © SoICT 2020 Technical Writing and Presentation 44 41 42 43 44 Technical Writing and Presentation 2016 12 Equations
Without equation numbers
Remember the full stop in the end of the equation, if the sentence finishes! “The prior probability of X is updated by Bayes rule, given new evidence Y :
”
If the sentence continues, then you need comma: ”The dependency is described by equation , where a is sg. and b is sg.” © SoICT 2020 Technical Writing and Presentation 45 Equations
With equation numbers
If you want to refer to some previous equation, you have to give it a label like for examples. © SoICT 2020 Technical Writing and Presentation 46 Mathematics
Only use mathematics where it is the most efficient way to convey the information.
Longer mathematical arguments, if they are really necessary, should go into an appendix. © SoICT 2017 Nhập môn CNTT&TT 47 Mathematics (continued)
Mathematical notation can be used to describe algorithms, data structures, automata, or any of the objects in computer science
A lot of difficulties for readers if the mathematics is badly presented
There are conventions of presentation for mathematics and mathematical concepts. © SoICT 2020 Technical Writing and Presentation 48 45 46 47 48 Technical Writing and Presentation 2016 13 Theoremes
Details of the proof can often be omitted in a paper.
Theorems, definitions, lemmas, propositions and key examples should be numbered.
If the proof need lemmas, put them at the right place for readability.
When stating your proof in a paper, Use means to convey your argument with the greatest possible clarity © SoICT 2020 Technical Writing and Presentation 49 Readability
Mathematics is usually presented in italics, to distinguish it from other text.
If a displayed formula is sufficiently important it should be numbered,
Notations should follow the conventions of your area rather than invent your own.
Use appropriate brackets, braces, parenthesis
Sentences should begin with a word, not digits or mathematics
Do not use a long stream of complex expression
Avoid unnecessary subscripts © SoICT 2020 Technical Writing and Presentation 50 Example Should be replaced with © SoICT 2020 Technical Writing and Presentation 51 52 49 50 51 52 Technical Writing and Presentation 2016 14 Lecture materials derived from:
Justin Zobel (2014), Writing for Computer Science, Springer.
Wilhelmiina Häamäläinen(2006), Scientific Writing for Computer Science Students, Course material, University of Joensuu.
Nicole Kelley (2006), Basics of Technical Writing, slides of MIT course. © SoICT 2020 Technical Writing and Presentation 53 53 Technical Writing and Presentation 2016 1 Technical Writing and Presentation Writing Technical Reports/Theses SOICT - 2020 TRƯỜNG ĐẠI HỌC BÁCH KHOA HÀ NỘI HANOI UNIVERSITY OF SCIENCE AND TECHNOLOGY Contents
Differences between a Report and a Thesis
Writing a technical report
Writing a thesis
Maping your ideas to text
Paragraphs © SoICT 2020 Technical Writing and Presentation 2 Differences between a Report and a Thesis
Reports describe a simple format used to present data and analyses, and then to come to some conclusion about that data, including recommendations if appropriate
A report is written for several people who know the topic very well © SoICT 2020 Technical Writing and Presentation 3
A thesis is often produced in order to obtain a higher academic degree.
A thesis is evidence of the candidate’s capacity to carry out independent research, to analyze and communicate the significant results of the work.
A thesis is a public document that may be read by many people
Generally the thesis represents a work of greater depth and academic inclination
Length of 60-120 pages is typical of a thesis, while a report is roughly half as many pages. Genre (style) of Technical Report
A technical report is a formal report designed to convey technical information in a clear and easily accessible format
It is divided into sections which allow different readers to access different levels of information. © SoICT 2020 Technical Writing and Presentation 4 1 2 3 4 Technical Writing and Presentation 2016 2 Structure of a technical report
Title page
Summary
Contents
Introduction
Body of the report
Conclusions
References
Bibliography
Acknowledgements
Appendixes (if appropriate) © SoICT 2020 Technical Writing and Presentation 5 Details of components
Title page: The page includes the title of the report.
Summary: includes important features, results and conclusions
Contents: Numbers and lists all section and subsection headings with page numbers © SoICT 2020 Technical Writing and Presentation 6 Details of components
Introduction : The objectives of the report and comments on the way the topic of the report is to be treated.
The sections which make up the body of the report:
Divided into numbered and headed sections.
Separate the different main ideas in a logical order
Conclusions: A short, logical summing up of the theme(s) developed in the main text © SoICT 2020 Technical Writing and Presentation 7 Details of components
References: Details of published sources of material referred to or quoted in the text
Bibliography: Other published sources of material, not referred to in the text but useful for background or further reading.
Acknowledgements: List of people who helped you research or prepare the report,
Appendices: further materials which are essential for full understanding of your report (e.g. large scale diagrams, computer code, raw data, specifications) but not required by a casual reader. Only comprehensive technical reports, such as some theses, have a bibliography. © SoICT 2020 Technical Writing and Presentation 8 5 6 7 8 Technical Writing and Presentation 2016 3 Planning the report
Collect your information: laboratory handouts, lecture notes, the reference books and journals
Creative phase of planning.
Write down topics and ideas from your researched material in random order.
Arrange them into logical groups.
Keep note of topics that do not fit into groups in case they come in useful later.
Put the groups into a logical sequence which covers the topic of your report.
Structuring the report: Using your logical sequence of grouped ideas, write out a rough outline of the report with headings and subheadings. © SoICT 2020 Technical Writing and Presentation 9 Writing the first draft
Who is going to read the report? The answer will affect the content and technical level, and is a major consideration in the level of detail required in the introduction.
Begin writing with the main text, not the introduction
Make rough sketches of diagrams or graphs.
Keep a numbered list of references as they are included in your writing and put any quoted material inside quotation marks
Write the Conclusion next, followed by the Introduction. Do not write the Summary at this stage. © SoICT 2020 Technical Writing and Presentation 10 Revising the first draft
The essence of a successful technical report lies in how accurately and concisely it conveys the intended information to the intended readership
Ask yourself these questions;
Does that sentence/paragraph/section say what I want and mean it to say? If not, write it in a different way.
Are there any words/sentences/paragraphs which could be removed without affecting the information which I am trying to convey? If so, remove them. © SoICT 2020 Technical Writing and Presentation 11 Finalizing the report and proofreading
Your report should now be nearly complete
an introduction, main text in sections, conclusions, properly formatted references and bibliography and any appendixes are completed.
It is the time to add the page numbers, contents and title pages and write the summary. © SoICT 2020 Technical Writing and Presentation 12 9 10 11 12 Technical Writing and Presentation 2016 4 The Summary
The summary, with the title,
indicate the scope of the report and give the main results and conclusions.
must be intelligible without the rest of the report, because many people may read, and refer to, a report summary but only a few read the full report
Purpose - a short version of the report and a guide to the report.
Length - short, typically not more than 100-300 words
Content - provide information, not just a description of the report. © SoICT 2020 Technical Writing and Presentation 13 Proofreading
Check every aspect of a piece of written work from the content to the layout
Never send or submit any piece of written work, from email to course work, without proofreading.
Before stapling your report, you must check it very carefully yourself.
Give your report to someone else to read carefully and check for any errors in content, style, structure and layout.
Do not forget to record the name of the proofreader in your acknowledgements. © SoICT 2020 Technical Writing and Presentation 14 Word processing / desktop publishing © SoICT 2020 Technical Writing and Presentation 15 Advantages Disadvantages Word processing and desktop publishing packages offer great scope for endless revision of a document. This includes words, word order, style and layout. Word processing and desktop publishing packages never make up for poor or inaccurate content They allow for the incremental production of a long document in portions which are stored and combined later They can waste a lot of time by slowing down writing and distracting the writer with the mechanics of text and graphics manipulation. They can be used to make a document look stylish and professional. Excessive use of 'cut and paste' leads to tedious repetition and sloppy writing. They make the process of proofreading and revision extremely straightforward If the first draft is word processed, it can look so stylish that the writer is fooled into thinking that it does not need proofreading and revision! Tips
Do not bother with style and formatting of a document until the penultimate or final draft.
Do not try to get graphics finalised until the text content is complete. © SoICT 2020 Technical Writing and Presentation 16 13 14 15 16 Technical Writing and Presentation 2016 5 Front Matter
Cover*
Label*
Title Page
Abstract
Table of Contents
List of Figures and Tables * May be an optional element © SoICT 2020 Technical Writing and Presentation 17 Cover and Label
A cover is used if the report is over 10 pages long
A label is placed on the cover to identify
Report tittlr and subtitle (if a subtitle is appropriate)
Author’s name
Publisher
Date of publication © SoICT 2020 Technical Writing and Presentation 18 Title page
The title page duplicates the information found on the front cover ( if the cover is used)
The title page also provides descriptive information that is used by organizations that provide access to information resources. © SoICT 2020 Technical Writing and Presentation 19 Select a title
Think about the reader’s first impression.
Include important and distinguishing key words, for example the words that somebody will use in a literature search.
Leave out any words that are not essential. Avoid meaningless expressions or longwinded descriptions. Every word must count. © SoICT 2020 Technical Writing and Presentation 20 17 18 19 20 Technical Writing and Presentation 2016 6 Abstract
An abstract is a short summary that provides an overview of the purpose, scope and findings contained in the report.
Purpose: identifies the issue, need or reason for the investigation
Scope: review the main points, extent and limits of the investigation
Findings: includes condensed conclusions and recommendations © SoICT 2020 Technical Writing and Presentation 21 Abstract
no more than 200 words
provides an “in a nutshell” description without providing underlying details
contains no undefined symbol, abbreviations, acronyms
makes no reference by number to any references or illustrative material © SoICT 2020 Technical Writing and Presentation 22 Abstract
Provides no background information.
Every word is important. Limit the use of words that do not convey important information to a minimum
The abstract is usually the last part of the report to be written.
Include in the abstract the keywords that someone may use to search for the report in a literature database. © SoICT 2020 Technical Writing and Presentation 23 Table of Contents
numbers and lists all section and subsection headings with page numbers
list the title and the beginning page number of each major section within the report (excluding the title page and the table of contents) © SoICT 2020 Technical Writing and Presentation 24 21 22 23 24 Technical Writing and Presentation 2016 7 List of Tables and Figures*
A list of figures and tables helps the reader to locate illustrations, drawings, photographs, graphs, charts, and tables of information contained in the report.
A figure is any drawing, photograph or chart is used to explain and supportthe technical information in the text
The figure number and title will appear below the image
Refer to a figure or table within the text and place the image close to the reference *May be an optional element © SoICT 2020 Technical Writing and Presentation 25 List of Tables and Figures*
A table is an arrangement of detailed facts or statistics that are arranged in a row and column format
The table number and tittle appear above the table *May be an optional element © SoICT 2020 Technical Writing and Presentation 26 Text
The text is the part of technical report in which the author
describes the methods, assumptions, and procedures
present and discusses the results
draws conclusions
recommend actions based on the results © SoICT 2020 Technical Writing and Presentation 27 Text
Summary
Introduction
Methods, assumption and procedures
Results and discussion
Conclusion
Recommendation
References © SoICT 2020 Technical Writing and Presentation 28 25 26 27 28 Technical Writing and Presentation 2016 8 Summary
Includes important features of the report
States the problem, method of investigation conclusions, and recommendations
Contains no new info that is not contained in the report
Does not contain references © SoICT 2020 Technical Writing and Presentation 29 Introduction
The Introduction prepares the reader to read the main body of the report.
This page focuses on the subject, purpose, and scope of the report
Subject: defines the topic and associated terminology; may include theory, historical background, and its significance
Purpose: indicates the reason for the investigation
Scope: indicates the extent and limits of the investigation © SoICT 2020 Technical Writing and Presentation 30 Methods, Assumptions, Procedures
The methods, assumptions, and procedures used in the investigation are described so the reader could duplicate the procedures of the investigation. Information in this section includes:
System of measurement
Types of equipment used and accuracy
Test methods used
The sections which make up the body of the report:
Divided into numbered and headed sections.
Separate the different main ideas in a logical order © SoICT 2020 Technical Writing and Presentation 31 Methods, Assumptions, Procedures
Methods: How did you discover the problem? What measuring tools were used? What measurement system was used?
Assumptions: What do you think, but cannot substantiate as fact?
Procedures: How did you gain a better understanding of the problem? © SoICT 2020 Technical Writing and Presentation 32 29 30 31 32 Technical Writing and Presentation 2016 9 Results and Discussion
The results and discussion section describes what you learned about the problem as a result of your research, identifies the degree of accuracy related to your findings, and gives the reader your view of the significance of your findings.
Results What did you learn about the problem through your research?
Discussion How accurate are your findings? What is the significance of the results of the research? © SoICT 2020 Technical Writing and Presentation 33 Conclusions
A short, logical summing up of the theme(s) developed in the main text
Restatement of Results
What are the factual findings that resulted from your research?
What are you implying as a result of these findings?
Concluding Remarks
What are your opinions based on the findings and results? © SoICT 2020 Technical Writing and Presentation 34 Recommendations*
A section called recommendations is often included in reports that are the result of tests and experiments, field trials, specific design problems, and feasibility studies.
The author may recommend additional areas of study and suggest a course of action, such as pursuing an alternate design approach
Additional Studies Is there information that still needs to be learned?
Suggested Actions What does the author want the reader to do with the information? *May be an optional element © SoICT 2020 Technical Writing and Presentation 35 References
The references section is the place where the author cites all of the secondary research sources* that were used to...
develop an understanding of the problem
support the information contained in the report © SoICT 2020 Technical Writing and Presentation 36 33 34 35 36 Technical Writing and Presentation 2016 10 Back Matter
The back matter supplements and clarifies the body of the report, makes the body easier to understand, and shows where additional information can be found.
The back matter may includes
Appendixes*
Bibliography*
List of Symbols, Abbreviations, and Acronyms Glossary*
Index*
Distribution List* © SoICT 2020 Technical Writing and Presentation 37 Appendixes*
Anything that cannot be left out of a report, but is too large for the main part of the report and would serve to distract or interrupt the flow belongs in the appendixes .For example:
Large tables of data Flowcharts
Mathematical analysis
Large illustrations
Detailed explanations and descriptions of test techniques and apparatus
Technical drawings *Mav be an optional element © SoICT 2020 Technical Writing and Presentation 38 List of Symbols, Abbreviations, and Acronyms*
If more than five symbols , abbreviations , or acronyms are used in the report, they are to be listed with their explanation. *Mav be an optional element © SoICT 2020 Technical Writing and Presentation 39 Parts of a thesis
Abstract
Introduction
Main chapters
Conclusions
References
Appendixes © SoICT 2020 Technical Writing and Presentation 40 37 38 39 40 Technical Writing and Presentation 2016 11 Examples of theses
A new application or method
Literature review
Suitablity of existing approaches to a new problem © SoICT 2020 Technical Writing and Presentation 41 Example1: a new application or method
The new application (a program) is in central role.
It has to be related to the existing research and evaluated.
Introduction: the problem
Background theory and main concepts
Related research (other existing solutions to the same or similar problems)
Your own application
Evaluation: comparison to other methods, empirical tests, or theoretical analysis
Conclusions © SoICT 2020 Technical Writing and Presentation 42 Example 2: Literature review
Introduction
Main concepts
Approaches + their analysis (2-3 chapters)
Or a chapter for comparison and analysis of all approaches
Conclusions © SoICT 2020 Technical Writing and Presentation 43 Ex3: Suitablity of existing approaches to a new problem
Introduction
The new problem + criteria for an ideal solution method
Potential solution methods + analysis of their suitability (2-3 chapters)
Possibly discussion (comparison, new solution ideas)
Conclusions © SoICT 2020 Technical Writing and Presentation 44 41 42 43 44 Technical Writing and Presentation 2016 12 Abstract
Tells compactly the research problem, methods and results.
At most 1 page, no literature references.
Key words. © SoICT 2020 Technical Writing and Presentation 45 Introduction
Define the problem clearly
Give suffiecient background information for the following chapters.
What is the purpose of the research? Main research questions?
What is the scope? Indicate explicitly all limitations and restricting assumptions! • Why the topic is important or interesting? • What methods are used? © SoICT 2020 Technical Writing and Presentation 46 Introduction (continued)
Briefly references to related research (just the main references – more references in chapter ”Related research” or throughout the thesis)
Emphasize your own contribution: what is original or new? © SoICT 2020 Technical Writing and Presentation 47 Conclusions
Just 1-2 pages! • Summarize the main results in a general level. • Tell what was your own conctribution and what was based on other sources. • Possibly also critics (e.g. limitations), alternative approaches, topics for future research. • No more new results and seldomly any references (at most for alterantive, unmentioned approaches) © SoICT 2020 Technical Writing and Presentation 48 45 46 47 48 Technical Writing and Presentation 2016 13 Appendixes
Additional material which is relevant to the research and is referred in the text.
No chapter numbers, but enumerate the appendixes (Appendix A, Appendix B,...).
If you have only one appendix, then just “Appendix”. © SoICT 2020 Technical Writing and Presentation 49 Process of thesis writing
Reading literature
Planning
To get started © SoICT 2020 Technical Writing and Presentation 50 Reading literature
Try to find the most relevant articles.
To get a wider perspective, search papers by different authors/research groups.
If there are several approaches to solve or study the problem,try to study something from all of them.
Use several digital libraries or bibliographies for searching – one collection may be biased.
Plan how much time you can spend for studying literature! In some point you have to stop collecting new material and begin to write. © SoICT 2020 Technical Writing and Presentation 51 Planning
Begin by brainstorming. Draw concept maps. Discuss with your friends or supervisors.
Write down all ideas which come into your mind.
Collect literature and scan through it. Select the most important sources.
Try to write the disposition as early as possible. Process it with your supervisor until it looks good (logical structure and order).
List the main research problems (in the form of questions) and write the introductory paragraphs for the chapters © SoICT 2020 Technical Writing and Presentation 52 49 50 51 52 Technical Writing and Presentation 2016 14 To get started
Arrange a comfortable working place. Reserve time for writing every day. Try to make writing a routine for you!
Set deadlines. Preferably fix them with your supervisor – it is always more effective.
Work together with your friends. You can set the deadlines, discuss your topics, and read each other’s texts. After good work you can reward yourself by doing something fun.
Imagine that you are writing to your friend about your research topic!
Summarize articles you have read. © SoICT 2020 Technical Writing and Presentation 53 To get started
Begin to write immediately, when your disposition is finished.
Write down ideas when they come – even in the middle of night
Invent good examples and write them down
If some part is difficult to write, beging from an easier one.
Write the difficult parts, when you are in a good working mood.
Draw figures which describe the some method or model and write a description.
Try to divide the problem or phenomenon into subproblems or parts and describe them separately.
Collect main concepts and write definitions for them. Fix the notations. © SoICT 2020 Technical Writing and Presentation 54 How to write the beginning of chapters?
Look at the opening sentences of similar compositions by other people
Possibly beginnings are
a summary,
a statement of the problem,
a hypothesis,
necessary and interesting background information,
a new idea,
an accepted procedure (then explain advantages of another procedure), ...
Don’t spend too much time trying to find an effective beginning – you can always modify it afterwards.
Go straight to the point and, if possible, refer to things that you expect your readers to know (vs. contructivism) © SoICT 2020 Technical Writing and Presentation 55 Revising
First of all, admit that the first draft(s) is not perfect! Ask criticts and respect it.
If possible, ask at least two people to read your thesis. Preferably one who is an expert on the subject, and one who is not.
Have a break when your work is finished. At least, sleep one night before revising the text yourself © SoICT 2020 Technical Writing and Presentation 56 53 54 55 56 Technical Writing and Presentation 2016 15 Technical hints
Read text aloud and check if it sounds well
Check all references. Especially, are names correctly spelled?
Save old versions, you may need them afterwards © SoICT 2020 Technical Writing and Presentation 57 Technical terms
If there is no widely accepted definition then 1. Tell whose definition you follow and give this definition with reference, or 2. Give a definition yourself and tell that in this work the term is defined as given.
Technical terms must be defined clearly and then used with accuracy and precision © SoICT 2020 Technical Writing and Presentation 58 Symbols
Don’t use the same symbol for different things!
Use indexes in a uniform manner.
If some special notation is widely used in literature, follow it.
If different sources use different notations, harmonize them
Do not use Greek letters if there is no reason. If there is a danger of confusion, then Greek letters are justified. © SoICT 2020 Technical Writing and Presentation 59 Equations
Avoid listing mathematical equations!
Try to integrate equations into sentences so that the results is readable.
Do not replace words by mathematical symbols (e.g. ∀) in the text © SoICT 2020 Technical Writing and Presentation 60 57 58 59 60 Technical Writing and Presentation 2016 16 Map your ideas to text
Writing w is a mapping from a set of ideas I to a set of scientific texts S, w : I → S.
Problem: Given a set of ideas i ∈ I, produce f(i) ∈ S © SoICT 2020 Technical Writing and Presentation 61 Instructions 1. Organize your ideas in a hierarchical manner, as a tree of ideas t (”minimal spanning tree” of idea graph) 2. Write the tree t as text such that
The root node of t corresponds to your topic (title)
Its children correspond to chapters
Their children and grand-children correspond to sections and subsections
Leaf nodes correspond to paragraphs (actual text) © SoICT 2020 Technical Writing and Presentation 62 Writing tree t
Each node n ∈ t contains three fields:
title(n): the main title or the name of the chapter, section or subsection. In leaf nodes (paragraphs) NULL
children(n): n’s children (chapters, sections or subsections). In leaf node NULL.
content(n): description of the idea in n. In non- leaf nodes very brief, in leaf nodes longer. © SoICT 2020 Technical Writing and Presentation 63 Properties of a good tree t
t is balanced: all paths from the root to a leaf are approximately of equal length, usually ≤ 4 or at most ≤ 5
Each node in t has a reasonable number of children k: k ≤ 2 and typically k ≤ 7 (in maximum k = 10)
For all leaf nodes n, the sizes of content(n) are balanced: each paragraph contains at least two sentences, but is not too long (e.g. ≤ 7 or ≤ 10 sentences)
For all non-leaf nodes m, the sizes of content(m) are balanced.
Exceptionally, in introduction, you can use more than one paragraph. © SoICT 2020 Technical Writing and Presentation 64 61 62 63 64 Technical Writing and Presentation 2016 17 Alg. 1 WriteTree(t) © SoICT 2020 Technical Writing and Presentation 65 Input: tree of ideas t Output: scientific text s 1 begin 2 Write title(n) 3 if (n is not leaf node) 4 begin Writing an introductory paragraph: 5 Write content(n) 6 for all u = child(n) 7 Write title(u) 8 for all u = child(n) 9 WriteTree(u) 10 end 11 else Writing a main paragraph: 12 Write content(n) 13 end Paragraphs
Helps the reader: tells what the paragraph is about.
Helps the writer: forces you to organize the material logically.
In an ideal case, you get a summary of the whole section by reading the topic sentences.
If you cannot write a clear topic sentence, ask yourself whether the paragraph is needed at all! © SoICT 2020 Technical Writing and Presentation 66 Combining sentences in a paragraph 1. Use (but do not overuse!) conjunctions or transitional words: • Time links, when you describe a process: then, next, first-secondthird, while, ... • Cause-effect links, when you describe reasons or results: therefore, as a result, thus, ...• Addition links, when you add points: in addition, moreover, similarly, ... • Contrast links, when you describe two sides of one thing: however, despite (=inspite of sg), ... Other: For example,... 2. Link the beginning of a sentence to the end of the previous sentence. E.g. the subject of sentence 2 is the object of sentence 1. ”A model consists of a model structure and model parameters. The model structure defines...” 3. Repeat the key terms througout the paragraph. However, do not repeat the same word twice in one sentence. © SoICT 2020 Technical Writing and Presentation 67 Dividing a section into paragraphs
Logically structured disposition (topic outline) is the most important thing in writing
An iterative process: 1. The main structure of the whole thesis: the main chapters and their contents in a couple of sentences or key words. The order of chapters. 2. For each chapter (or an article), the main sections + key words, introductory sentences or phrases. The order of sections. 3. In each section, the subsections or paragraphs. The introductory sentences, key words, and the order of paragraphs. List the related tables and figures. © SoICT 2020 Technical Writing and Presentation 68 65 66 67 68