Jürgen Börstler, Blekinge Institute of Technology © 2014 Updated 2020‐02‐26 Writing Guidelines Avoid pompous/pretentious language and clichés Academic writing should be clear and objective. Trying to impress others by using uncommon and pretentious words, trite expressions (clichés), and overly complicated sentences will threaten clarity and objectivity. Readers might perceive your writing as biased and therefore not trustworthy. Language that can be perceived as preaching, exaggerating or bragging should be avoided in academic writing. Use consistent and precise terminology Writing science differs from writing prose. In school, you were probably taught to vary your vocabulary. Doing so is a good idea for writing prose. However, in science, it is important to stick to the terminology you have introduced. Using different words for the same concept will confuse your readers and will make it more difficult for you to express yourself sufficiently precise. Be consistent throughout Consistency is not only important for terminology. Consistency is also important for formatting, numbering schemes and the design and layout of figures, tables and graphs. Inconsistencies will confuse, distract, or even annoy your readers. Avoid acronyms Acronyms hinder readability. Fewer acronyms will improve the readability and the understandability of your work. You should therefore avoid acronyms that are not commonly known by your audience. You should also avoid acronyms for terms that you use only a few times. If you need to introduce acronyms, introduce them as early as possible and then use them consistently throughout your work. When the concept is used for the first time, write it out and put the acronym after in parentheses. Then you can use the acronym throughout. Avoid noun chunks Noun chunks are strings of consecutive nouns or noun phrases1. They are often used to describe technical concepts, e.g., large-scale embedded systems regression testing. There are rules for the “word binding” of noun phrases, however, these rules are complex and sometimes ambiguous. The interpretation of a noun chunk can therefore be difficult, and your terminology becomes imprecise. Is large-scale embedded systems regression testing large-scale regression testing for embedded systems, regression testing for large-scale embedded systems, large-scale embedded regression testing for systems, or something different? Noun chunks are related to so-called garden-path sentences2, which are grammatically correct, but difficult to parse. Such sentences easily mislead readers. The underlying problem is that the 1 A noun phrase is a group of words containing a noun. As a part of speech, a noun phrase is used as if it were a single noun. 2 https://en.wikipedia.org/wiki/Garden-path_sentence 1 (4) Jürgen Börstler, Blekinge Institute of Technology © 2014 Updated 2020‐02‐26 same word (or phrase) can belong to different word classes (e.g., adjective, verb, or noun). Technical definitions might give words new meanings and these meanings might even change the class of the word. In the sentence The complex houses married and single soldiers and their families a reader might interpret complex as an attribute of houses, i.e. complex houses is interpreted as a noun phrase (the houses of a housing complex). This renders the rest of the sentence meaningless, though. By interpreting complex as a noun and houses as a verb, the sentence makes perfect sense. When minor errors in spelling and grammar are combined with noun chunks, it can become impossible to understand what you want to convey. There can be several options for correcting a sentence that might change its meaning in one direction or another. Give the following sentence a try and discuss the result with your fellow students: The reviews forms management processes affect quality negatively. Cite sources responsibly Make sure to read a source before you cite it so that you understand its connection to your work. If you don’t, it will be difficult for you to explain to your readers the connection between a claim and the source(s) you cite to support it. Do not simply use the first source you find using Google Scholar and do not cite a specific source just because others do so. There are too many sloppy citations “out there” to trust the citations of others. Excellent examples of perceived truths of Software Engineering that lack evidence are discussed in the The Leprechauns of Software Engineering (Bossavit 2012). When discussing and synthesizing related work, make sure to focus on the results of these works and their connections to your work. Focus on what is relevant to your work, not on author names, publication titles etc. Check your reference data Check each of your references for completeness and correctness. How can a reader trust your results, when you cannot even get the references right? Incorrect or incomplete information in your reference section give a sloppy impression and might indicate that the rest of your work is sloppy as well. Please note that the information on references stored in literature databases and by Google Scholar is often incomplete, incorrect or inconsistently formatted. In particular conference proceedings are referenced inconsistently, e.g., 2005 International Symposium on Empirical Software Engineering, 2005. instead of Proceedings of the 4th International Symposium on Empirical Software Engineering. Make sure to check all data carefully and update it when necessary. Write short sentences and short paragraphs “The trick to writing short sentences is to restrict each sentence to one and only one idea. Resist the temptation to embed multiple clauses or parentheticals, which challenge comprehension. Instead, break long, rambling sentences into crisp, more concise ones.” (Gernsbacher 2018, p 407) “Combine short sentences into short paragraphs. Aim for around five sentences per paragraph. ... The prototypical five-sentence paragraph comprises a topic 2 (4) Jürgen Börstler, Blekinge Institute of Technology © 2014 Updated 2020‐02‐26 sentence, three supporting sentences, and a conclusion sentence.” (Gernsbacher 2018, p 407) The last paragraph in Section “Avoid noun chunks” above could, for example, have been started as follows: When minor errors in spelling and grammar are combined with noun chunks, it can become impossible for the reader to figure out what you want to convey, since there can be several options for correcting a sentence leading to sentences that change its meaning in one direction or another. ... Splitting the sentence at since plus some rewording (to resolve the unclear reference its) made the corresponding passage in Section “Avoid noun chunks” much easier to read and to understand. Use parallel structure Parallel structure means using consistent parts of speech for text parts that belong together. Parallel structure makes texts easier to read and to understand, since it helps readers to “see” the connection(s) or comparison(s) you had in mind when writing the text. Parallel structure in lists lets your text flow better. Putting your headers in parallel form makes the organization of your work more coherent and therefore easier to understand. “For example, “Active reconstruction of a past experience differs from passively hearing a story about it” lacks parallel structure. Better would be “Actively reconstructing a past experience differs from passively hearing a story about it.” Parallel structure makes it easier for your reader to make the comparison you want them to. On a broader scale, make sure that your organization has parallel emphasis: The topics given emphasis in the introduction should receive comparable emphasis in the discussion.” (Simons 2019, p 3) Compare the list versions below as an example. More comparisons of parallel and non-parallel structures can be found at https://examples.yourdictionary.com/parallel-structure-examples.html. Not in parallel form Parallel form (nouns) Parallel form (verbs) The technique consists of the following five subprocesses. 1. Assigning weights to stakeholders, 2. Setting communication parameters, 3. Assigning values to constraints, 4. Requirements prioritization, and 5. Negotiation. The technique consists of the following five subprocesses. 1. Stakeholder weight assignment, 2. Communication parameter setting, 3. Constraint value assignment, 4. Requirements prioritization, and 5. Requirements negotiation. The technique consists of the following five subprocesses. 1. Assigning weights to stakeholders, 2. Setting communication parameters, 3. Assigning values to constraints, 4. Prioritizing requirements, and 5. Negotiating requirements. You not only need to summarize your sources; you also need to analyse and synthesise them A good summary focuses on the most important points of a source and describe them clearly, accurately and concisely IN YOUR OWN WORDS. A summary captures the source’s intentions and conclusions, which might be different from your interpretation of the source. objective summary of key points of a source. 3 (4) Jürgen Börstler, Blekinge Institute of Technology © 2014 Updated 2020‐02‐26 A good analysis adds your interpretation to a summary but does always clearly sperate your intentions/ interpretations/ conclusions/ ideas from those of the original source. An analysis focuses on one source. evaluation of a source. A good synthesis weaves together several summaries and analyses and discusses how they are related. A good synthesis describes the gist of the sources and their analysis, i.e. what the sources—taken together—mean for the field in general, and your work in particular. answer to “so what” question. Ideas that won’t fly This section quotes Sørensen’s (2005) description of ideas that are insufficient for papers. These ideas also won’t fly for theses at BTH. If the project idea for your thesis matches one of the following, it will not be approved: The “great idea” thesis “I have just had this great idea! I do not know if anyone else has ever had the same idea, because I’ve not checked, and I’m rather new in this field. Anyway, my idea is brilliant, so I really would like to share it with you all.” The “other people’s ideas” thesis “I have just read this great book that I really like a lot. I’ll just give you a short resumé of the interesting points in the book.” The “software hacker” thesis “I have just built this great computer system. It is not based on previous theories or empirical findings. I am not very theoretical myself, but the system has a lot of fantastic features, and the interface is really neat.” The “theory hacker” thesis “I have come up with this theory; conceptual framework; model. It is not related to other theories; conceptual frameworks; models, or any empirical data for that matter. Most of the concepts have been defined differently by all the big shots in the field, but I just do not like their categories so I have invented my own.” The “multiple point” thesis “I have just completed a major research effort where I did a lot of interesting things. I think that you could learn a lot by reading this paper describing all aspects of my work.” References Bossavit, L. (2012). The Leprechauns of Software Engineering: How folklore turns into fact and what to do about it. Leanpub. An excerpt is available at https://leanpub.com/leprechauns. Accessed 2019-07-17. Gernsbacher, M. A. (2018). Writing empirical articles: Transparency, reproducibility, clarity, and memorability. Advances in Methods and Practices in Psychological Science, 1(3), 403-414. Mensh, B., & Kording, K. (2017). Ten simple rules for structuring papers. PLoS Computational Biology, 13(9). Simons, D. (2019). Writing Guide. Version 1.5. Available at http://www.dansimons.com/resources/ writing_tips.html. Accessed 2019-07-10. Sørensen, C. (2005). This is Not an Article. Just some thoughts on how to write one. Available at http://stuff.carstensorensen.com/papers/ThisIsStillNotAnArticlePre.pdf. Accessed 2019-07-10. 4 (4)
