Bài giảng Technical writing and presentation - Chương 11: Writing scientific text in computer science

Technical Writing and Presentation

2016

Scientific Writing for Computer Science

TRƯỜNG ĐẠI HỌC BÁCH KHOA HÀ NỘI

HANOI UNIVERSITY OF SCIENCE AND TECHNOLOGY

1. How to write scientific texts in computer

science?

2. How to write in English?

Technical Writing and Presentation

3. How to write a technical report / thesis?

Writing scientific text in computer science

SOICT - 2020

Technical Writing and Presentation

2

1

2

Contents

General style

° General style

° What is style?

° Scientific writing style

° References and citations

° Acknowledgements

° Formatting

° Use of tables, figures, and similar elements.

° Mathematics

Technical Writing and Presentation

3

Technical Writing and Presentation

4

3

4

1

Technical Writing and Presentation

2016

Genre (style)

Scientific writing style

° Fundamental aims of science writing: to

° The manner of expression is the

writing style: how well you

be exact, clear, and compact.

communicate with likely readers.

° Compact is usually clear!

° Scientific writing must be plain and

straightforward but not dull. It can

have style.

° Other desirable properties: smooth and

objective

° Good style makes your writing easy

to understand. It can persuade

readers that work is of value.

Technical Writing and Presentation

5

Nhập môn CNTT&TT

6

5

6

Exact

Avoid ambiguity

°

Example

° Word choice

° Avoid vague expressions which are typical

UAn 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.

for the spoken language

° Make clear what the pronouns refer to

° Avoid ambiguity

VAn 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

° Avoid illogical comparisons

° Correct grammar

are confusing if used in another way.

° For example,

° Formula, expression, equation

° Average, mean

° Subset, proper subset, strict subset.

Nhập môn CNTT&TT

7

Technical Writing and Presentation

8

7

8

2

Technical Writing and Presentation

2016

Use Words Efficiently

Clear

° Use illustrative titles which describe the essential in a

° Never use two words when one word will do.

chapter or a section.

° Write a brief introductory paragraph in the beginning

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.

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

Example 2: The fluctuating salinity of EGP

concerns many environmentalists, scientists,

and residents.

exact measurements.

° Use punctuation to support meaning.

Technical Writing and Presentation

9

Nhập môn CNTT&TT

10

9

10

Define the Unfamiliar

Avoid jargon

° Jargon: a vocabulary particular to a place

• If you must abbreviate, define the term in its first

occurrence, and put abbreviations in parentheses

of work (abbreviations, slang)

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.

° Audience familiarity with the topic

determines appropriate use of jargon

U For the first year, the links with SDPC and the

HAC were not connected, and all required OCS

input data were artificially loaded. Thus

• Italicize first occurrence of unfamiliar terms and

define them right away

CATCH22 and MERWIN were not available.

Example Retina is a light-sensitive tissue, found at

the back of the eye, that converts light impulses to

nerve impulses.

VBecause some of the links in the computer

system were not connected the first year, we

could not run all the software codes.

Technical Writing and Presentation

12

Technical Writing and Presentation

11

12

3

Technical Writing and Presentation

2016

Compact

Smooth

° Say only what needs to be said!

° Short words and short sentences are

° Verbs: Stay within the chosen tense! No

unnecessary shifts in verb tense within – the

same paragraph – in adjacent paragraphs

always easier to comprehend

° Weed out too detailed descriptions.

° Don’t describe irrelevant or trivial

° Use verbs rather than their noun equivalents

° Prefer active to passive voice

observations

° Avoid long noun strings!

° Avoid wordiness, Use no more words than

are necessary. Redundant words and

phrases should be omitted.

° Each pronoun should agree with the referant

in number and gender.

° Transitional words help to maintain the flow

° Avoid too long sentences and paragraphs

of thought

Nhập môn CNTT&TT

13

Nhập môn CNTT&TT

14

13

14

Smooth

Active voice

° 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.

° 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.

° 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

Nhập môn CNTT&TT

15

Technical Writing and Presentation

16

15

16

4

Technical Writing and Presentation

2016

Example: active voice vs passive voice

References and Citations

° References and citations

UThe 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.

° 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

VThe 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.

° References must be in standardized

format

Technical Writing and Presentation

17

Technical Writing and Presentation

18

17

18

Purposes of references

An appropriate reference is

° Relevant

° up-to-date

° reasonably accessible

° Refer to the original paper

° well-written material

° Demonstrate that your work is new

° Demonstrate your knowledge of the

research area

° Help the reader to judge whether your

° book, conference paper, journal article in preference

statements are reliable.

to a workshop paper

° workshop paper in preference to a manuscript

° Pointers to background reading.

° 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.

Technical Writing and Presentation

19

Technical Writing and Presentation

20

19

20

5

Technical Writing and Presentation

2016

Examples

Citations

° Refer to a result in an inaccessible paper, do

° Citations should be punctuated

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:

° Never treat a bracketed expression,

whether a citation or otherwise, as a

word.

UIn [2] such cases are shown to be rare.

VSuch cases have been shown to be rare [2].

° Marsden [16] has used an approach in whichꢀ

Other work (Marsden 1991) has used an

approach in whichꢀ

Technical Writing and Presentation

21

Technical Writing and Presentation

22

21

22

Citations

Acknowledgements

° Should thank everyone who made a contribution,

• The cite should be close to the material it relates to

whether advice, proofreading, coding, or whatever

° Two common forms of acknowledgement

° list the people who have helped

UThe original algorithm has

asymptotic cost O(n²) 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)

VThe original algorithm has

asymptotic cost O(n₂) but

low memory usage

° explain each person’s contribution

(Keele 1989). Thus it is not

entirely superseded by

Ahlberg’s approach

° Write “I am grateful to” , “I thank” or “Thanks to”

instead of “I would like to thank” or “I wish to thank”

(Ahlberg 1996), which,

although of cost O(n log n),

requires a large in-memory

array

Technical Writing and Presentation

23

Technical Writing and Presentation

24

23

24

6

Technical Writing and Presentation

2016

Formatting

Fonts

° Fonts

° Standard choices: Times New Roman,

Cambria.

° Indentation

° Layout

° Three fonts for computing and

mathematical writing : plain, italic, bold

° Headings

° Numbering

° Underlining is used for emphasis.

°

Technical Writing and Presentation

25

Technical Writing and Presentation

26

25

26

Indentation

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

° Indentation is used to indicate the start of

a new paragraph

° Use right-justified as well as left-justified

° Pages should be numbered

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.

Technical Writing and Presentation

27

Nhập môn CNTT&TT

28

27

28

7

Technical Writing and Presentation

2016

Headings

Numbering

° Use heading and sub-headings to break

° The use of numbering and type size and

up the text and to guide the reader.

style can clarify the structure as follows;

° 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.

Nhập môn CNTT&TT

29

Nhập môn CNTT&TT

30

29

30

Use of tables, figures, and similar elements

Figures and tables

° Figures and tables

° Diagrams

° General rules

° Vector graphics

° Captions

° Graphs

° Lists

° Expressions

° Algorithms

° Examples and definitions

° Equations

Technical Writing and Presentation

31

Technical Writing and Presentation

32

31

32

8

Technical Writing and Presentation

2016

General rules

Vector graphics

° Figures illustrate the models or the results, and

° Use vector graphics, not raster graphic

tables give summaries.

(bitmaps)! There is a big difference in quality:

° 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.

Technical Writing and Presentation

33

Technical Writing and Presentation

34

33

34

Tables

Captions

° Is a table the best way to present your

information?

° Consider graphs, bar charts or pie charts.

° 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.

° 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.

° 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.

° Complicated tables should go in an appendix.

Nhập môn CNTT&TT

35

Technical Writing and Presentation

36

35

36

9

Technical Writing and Presentation

2016

Expressions

Diagrams

° Keep them simple.

° When you refer to figures and tables you

can use the following expressions:

° The results are summarized/reported in

° Draw them specifically for the report.

° Put small diagrams after the text

Table 1

reference and as close as possible to it.

° The results are represented in

° Figure 2 illustrates

° In the Figure we observe

° The model is given in Figure 7

° etc.

° Think about where to place large

diagrams.

Technical Writing and Presentation

37

Nhập môn CNTT&TT

38

37

38

Graphs

Lists

° Graphs must be used particularly when trends are

° Lists are not separate objects, and they

shown or series of data are compared.

are introduced in the text.

° 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.

° Use list only when they are necessary!

E.g. ”The main criteria of X are (the following):”

– Criterion 1

° The quantity of information in one graph must be

limited so that the different symbols can be clearly

distinguished.

– 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!

° The axes of a graph must be named in words, in

conjunction with units.

Nhập môn CNTT&TT

39

Technical Writing and Presentation

40

39

40

10

Technical Writing and Presentation

2016

Algorithms

Example of Algorithm

° 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 x_i∈ X, T = T ∪ {p_i}, find such S ⊆ T that

q(S),...

° If you writer longer algorithms, insert them into a

figure or an environment of their own.”

Technical Writing and Presentation

41

Technical Writing and Presentation

42

41

42

Definitions

Expressions for referring to a definition

° A good definition

° The definition of ... is the following:

° The definition of ... is as follows:

° Formally, we define ꢀ

° 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

Technical Writing and Presentation

43

Technical Writing and Presentation

44

43

44

11

Technical Writing and Presentation

2016

Equations

° With equation numbers

° 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 you want to refer to some previous

equation, you have to give it a label like

for examples.

° If the sentence continues, then you need comma:

”The dependency is described by equation

< equation >,

where a is sg. and b is sg.”

Technical Writing and Presentation

45

Technical Writing and Presentation

46

45

46

Mathematics

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

° 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.

mathematics and mathematical concepts.

Nhập môn CNTT&TT

47

Technical Writing and Presentation

48

47

48

12

Technical Writing and Presentation

2016

Theoremes

Readability

° Mathematics is usually presented in italics, to

distinguish it from other text.

° If a displayed formula is sufficiently important it

° Details of the proof can often be omitted in a

paper.

° Theorems, definitions, lemmas, propositions

should be numbered,

° Notations should follow the conventions of your

and key examples should be numbered.

area rather than invent your own.

° If the proof need lemmas, put them at the

° Use appropriate brackets, braces, parenthesis

° Sentences should begin with a word, not digits or

right place for readability.

mathematics

° Do not use a long stream of complex expression

° Avoid unnecessary subscripts

° When stating your proof in a paper, Use

means to convey your argument with the

greatest possible clarity

Technical Writing and Presentation

49

Technical Writing and Presentation

50

49

50

Example

Should be replaced with

Technical Writing and Presentation

51

52

51

52

13

Technical Writing and Presentation

2016

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.

Technical Writing and Presentation

53

14

Bài giảng Technical writing and presentation - Chương 11: Writing scientific text in computer science - Vũ Văn Thiệu