CS790Technical Writing

for Computer ScientistsSummer 2007

2007.8.7. 3-6pmSue Moon

KAIST

2

Understanding Style

Lessons in Clarity and Grace

3

In early 19th century, James Cooper wrote

The love of turgid expressions is gaining ground, and ought to be corrected. One of the most certain evi-dences of a man of high breeding, is his simplicity of speech: a simplicity that is equally removed from vulgar-ity and exaggeration…. Simplicity should be the firm aim, after one is removed from vulgarity…. In no case, how-ever, can one who aims at turgid language, exaggerated sentiments, or pedantic utterances, lay claim to be either a man or a woman of the world.

4

He should have written

We should discourage those who love turgid language. A well-bred person speaks simply, in a way that is neither vulgar nor exaggerated. No on can claim to be a man or woman of the world who exaggerates sentiments or de-liberately speaks in ways that are turgid or pedantic.

5

In textbooks we confront

Recognition of the fact that systems [of grammar] differ from one language to another can serve as the basis for serious consideration of the problems confronting trans-lators of the great works of world literature originally written in a language other than English.

6

which should have been

When we recognize that languages have different gram-mars, we can consider the problems of those who trans-late great works of literature into English

7

Writing for Computer Science

Too often, however, the only help a novice receives is an advisor’s feedback on drafts of papers. Such interaction can be far from adequate: many scientists have little ex-perience of writing extended documents.

For some advisors, the task of helping a student to write well is not one that comes naturally, and it can be a dis-traction from the day-to-day work of research and teach-ing.

8

Writing for Computer Science

Most scientists can produce competent papers simply by following elementary steps: create a logical organization, use concise sentences, revise against checklists of possi-ble problems, seek feedback. Like many skills, writing improves through practice and a willingness to accept and learn from criticism.

In contrast to books-which can represent an author’s opinions as well as established knowledge-the content of a paper must be defended and justified.

9

Writing for Computer Science

1. Introduction2. Good Style3. Style specifics4. Punctuation5. Mathematics6. Graphs, figures, and ta-

bles7. Algorithms

8. Editing9. Writing up10. Doing research11. Experimentation12. Referencing13. Ethics14. Giving presentation

10

Writing for Computer Science

A paper should be an objective addition to scientific knowledge, not a description of the path you took to the result. Style is not just about how to write, but is also about what to say.

11

Writing for Computer Science

Skepticism is key to good science. For an idea to survive, other scientists must be persuaded of its relevance and correctness-not with rhetoric, but in the established framework of a scientific publication. New ideas must be explained clearly to give them the best possible chance of being understood, believed, remembered, and used. This begins with the task of explaining our ideas to the person at the next desk, or even to ourselves. It ends with publication, that is, an explanation of results to the research community. Thus good writing is a crucial part of the process of good science.

12

Style

is not about correct use of grammar, but about how well you communicate with likely readers

13

Good Style

Economy The volume of information has been rapidly increasing in the past few

decades. While computer technology has played a significant role in en-couraging the information growth, the latter has also had a great impact on the evolution of computer technology in processing data throughout the years. Historically, many different kinds of databases have been developed to handle information, including the early hierarchical and network models, the relational model, as well as the latest object-oriented and deductive databases. However, no matter how much these databases have im-proved, they will have their deficiencies. Much information is in textual format. This unstructured style of data, in contrast to the old structured record format data, cannot be managed properly by the traditional data-base models. Furthermore, since so much information is available, storage and indexing are not the only problems. We need to ensure that relevant information can be obtained upon querying the database.

14

Good Style

Economy The volume of information has been rapidly increasing in the past few

decades. While computer technology has played a significant role in en-couraging the information growth, the latter has also had a great impact on the evolution of computer technology in processing data throughout the years. Historically, many different kinds of databases have been developed to handle information, including the early hierarchical and network models, the relational model, as well as the latest object-oriented and deductive databases. However, no matter how much these databases have im-proved, they will have their deficiencies. Much information is in textual format. This unstructured style of data, in contrast to the old structured record format data, cannot be managed properly by the traditional data-base models. Furthermore, since so much information is available, storage and indexing are not the only problems. We need to ensure that relevant information can be obtained upon querying the database.

15

Good Style

Economy Be egoless If someone dislikes anything you have written, remember that

it is readers you need to please, not yourself.

16

Good Style

Tone simple, short, direct Sometimes the local network stalls completely for a few sec-

onds. This is what we call the “Grimwade effect”, discovered serendipitously during an experiment to measure the impact of server configuration on network traffic.

Sometimes the local network stalls for a few seconds. We first notice this effect during an experimental measurement of the impact of server configuration on network traffic.

17

Good Style

Examples Use an example whenever it adds clarification.

18

Good Style

Motivation Link text together as a narrative “Together these results show that the hypothesis holds for lin-

ear coefficients. The difficulties presented by non-linear coeffi-cients are considered in the next section.”

Balance Within a paper, each topic should be discussed to a similar

depth.

19

Good Style

Voice Tree structures can be utilized for dynamic storage of terms. Terms can be stored in dynamic tree structures.

When we conducted the experiment it showed that our con-jecture was correct.

The experiment showed that our conjecture was correct.

20

Good Style

The upper hand Showing off is snobbish and tiresome.

Obfuscation Making statements in ambiguous or convoluted terms The status of the system is such that a number of components

are now able to be operated. Several of the system’s components are working.

Analogies Writing a program is like building a model with connector

blocks.

21

Good Style

Straw men Indefensible hypothesis that an author describes for the sole

purpose of criticizing it. Example of rhetoric—of attempting to win an argument

through presentation rather than reasoning. Most users prefer the graphical style of interface. We believe that most users prefer the graphical style of inter-

face. Another possibility would be a disk-based method, but this ap-

proach is unlikely to be successful. Another possibility would be a disk-based method, but our ex-

perience suggests that this approach is unlikely to be success-ful.

22

Good Style

Reference and citation They demonstrate your knowledge of the research area, which

helps the reader to judge whether your statements are reli-able.

Robinson’s theory suggests that a cycle of handshaking can be eliminated, but he did not perform experiments to confirm his results [22].

Robinson’s theory suggests that a cycle of handshaking can be eliminated [22], but as yet there is no experimental confirma-tion.

23

Good Style

Quotation Hamad and Quinn (1990) show that “similarity [sic] is function-

ally equivalent to identity”; note that similarity in this context means homology only, not the more general meaning used in this paper.

Hamad and Quinn (1990) show that homology “is functionally equivalent to identity”.

[sic] to indicate that an error is from the original quote “David regards it as ‘not worty [sic] of consideration”

24

Good Style

Acknowledgements scientific paper vs books/theses I would like to thank .... I wish to thank ...ÞI wish to thank ... but for some reason I am unable to do so.

I am grateful I thank Thanks to

25

Good Style

Grammar don’t split infinitives don’t begin a sentence with “and” or “but” too much sloppy grammar can annoy readers

Beauty aim for simplicity and clarity

26

Style Specifics

Titles and heading complicated titles with long words hard to swallow if too short, it could be contentless complete sentences can look odd

Lists and TreesLists, Trees

Index organizationsB-trees vs B-tree indexes

Subsection ok, but sub-subsection hardly needed

27

Style Specifics

The opening paragraphs Direct and straightforward Intelligible to any likely reader Describe what you have done without the details of how it was

done

Trees, especially, binary trees, are often applied—indeed indis-criminately applied—to management of dictionaries.

Dictionaries are often managed by a data structure such as a tree, but trees are not always the best choice for this applica-tion.

28

Style Specifics

The opening paragraphs This paper does not describe a general algorithm for transac-

tions. General-purpose transaction algorithms guarantee freedom

from deadlock but can be inefficient. In this paper we describe a new transaction algorithm that is particularly efficient for a special case, the class of linear queries.

In this paper we describe a new programming language with matrix manipulation operators.

Most numerical computation is dedicated to manipulation of matrices, but matrix operations are difficult to implement effi-ciently in current high-level programming languages. In this paper we describe a new programming language with matrix manipulation operators.

29

Style Specifics

The opening paragraphs Use of digital libraries is increasingly common. It is important that the cost of disk accesses be reduced in

query processing.

Digital libraries provide fast access to large numbers of docu-ments.

Query processing can involve many disk accesses.

30

Style Specifics

The opening paragraphs Underutilization of main memory impairs the performance of

operating systems. Operating systems are traditionally designed to use the least

possible amount of main memory, but such design impairs their performance.

Many user interfaces are confusing and poorly arranged. Inter-faces are superior if developed according to rigorous principles.

Many user interfaces are confusing and poorly arranged. We demonstrate that interfaces are superior if developed accord-ing to rigorous principles.

31

Style Specifics

Tense Present tense is used for eternal truths Better to write “related issues are discussed below” than to

write “related issues will be discussed below” Past tense is used to describing work and outcomes“Although theory suggtests that the Klein algorithm has asymp-

totic complexity O(n^2), in our experiment the trend observed was O(n).”

“Willer (1999) shows that the space is open.”“Haast (1986) postulated that the space is bounded, but Willert

(1999) has since shown that it is open.”

32

Style Specifics

Qualifiers Use at most one qualifier such as “might”, “may”, “perhaps”,

“possibly”, “likely”, “likelihood”, or “could” It is perhaps possible that the algorithm might fail on unusual

input. The algorithm might fail on unusual input. The standard method is simply too slow. “totally”, “completely”, “truly”, “highly”, “usually”, “accord-

ingly”, “certainly”, “necessarily”, “somewhat”

33

Style Specifics

Padding adding together after the end of in the region of cancel out conflated together let us now consider cooperate together currently ... today divided up give a description of during the course of

of fast speed first of all for the purpose of free up in view of the fact joined up of large size semantic meaning merged together the vast majority of completely omtimized