CS790 Technical Writing for Computer Scientists Summer 2007

1. CS790Technical Writing for Computer ScientistsSummer 2007 2007.8.7. 3-6pm Sue 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 evidences of a man of high breeding, is his simplicity of speech: a simplicity that is equally removed from vulgarity and exaggeration…. Simplicity should be the firm aim, after one is removed from vulgarity…. In no case, however, 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 deliberately 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 translators 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 grammars, we can consider the problems of those who translate 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 experience 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 distraction from the day-to-day work of research and teaching.

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 possible 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 • Introduction • Good Style • Style specifics • Punctuation • Mathematics • Graphs, figures, and tables • Algorithms • Editing • Writing up • Doing research • Experimentation • Referencing • Ethics • 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 encouraging 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 improved, 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 database 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 encouraging 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 improved, 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 database 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 seconds. 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 linear coefficients. The difficulties presented by non-linear coefficients 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 conjecture 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 interface. • Another possibility would be a disk-based method, but this approach is unlikely to be successful. • Another possibility would be a disk-based method, but our experience suggests that this approach is unlikely to be successful.

22. Good Style • Reference and citation • They demonstrate your knowledge of the research area, which helps the reader to judge whether your statements are reliable. • 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 confirmation.

23. Good Style • Quotation • Hamad and Quinn (1990) show that “similarity [sic] is functionally 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 Trees • Lists, Trees • Index organizations • B-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 indiscriminately 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 application.

28. Style Specifics • The opening paragraphs • This paper does not describe a general algorithm for transactions. • 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 efficiently 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 documents. • 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. Interfaces are superior if developed according to rigorous principles. • Many user interfaces are confusing and poorly arranged. We demonstrate that interfaces are superior if developed according 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 asymptotic 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”, “accordingly”, “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