====== Scientific writing ====== The skills required for science and writing -- are they different? "The best science is based on straightforward, logical thinking, and it isn't artistic prose that we expect in [scientific texts] -- we expect clarity." [Writing for Computer Science, J. Zobel] === Be simple === * do not divagate * do not pad * no run-on sentences * one idea/fact per sentence, one line of thought per paragraph * Be concise and precise * be unambiguous (e.g., are back references such as "those" or "it" clear?) * concrete statements instead of vague descriptions such as "many", "good", "quite" etc. === Avoid === * abbreviations. If used, use them consistently. * footnotes, because they interrupt the reading flow. * parentheses. Either it is important to say/read -> write it, or it is not important -> do not write it. === Tense === * facts: present tense * observations (in own experiments, previous studies): Past tense === Technical terms === * introduce (//italics//, \emph{...}) * re-use consistently * use existing terms instead of inventing new, own terms === Thread === * vary connecting phrases (many authors overuse "However, ...") * introductory sentence per section * Refer to each figure/table. Refer at that point where reader should switch from main text to figure/table. **Be critical on your own text.** "... 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." [Writing for Computer Science, J. Zobel] "There is no excuse for a report that contains spelling errors." [Writing for Computer Science, J. Zobel] ===== Citations ===== === Why to care about previous work? === * do not invent the wheel a second time * appreciate previous work * demonstrate your knowledge of the research area * provide links to other relevant, interesting, background literature === What should you cite? === - books, book chapters - review articles - journal articles (peer-reviewed) - conference articles (peer-reviewed) * avoid: PhD theses, posters, personal communication * if you have several choices: primal publication, most recent publication, most important publication, most elegant publication? === How? === * name-year system: "BLAST (Altschul et al. 1990) and FASTA (Pearson 1990) are based on pairwise alignment." * number system: "BLAST [11] and FASTA [17] are based on pairwise alignment." * Emphasize others work by stating authors and year of publication: "In 1990, two methods based on pairwise alignment have been introduced: BLAST by Altschul et al. [1] and FASTA by W. Pearson [17]." === Where? === * as close to the statement as possible * directly after naming a method/algorithm/tool * in case of several statements, after the last === BibTeX === * blabla~\cite{KEY1, KEY2} * blabla~\cite[Chapter 3]{BOOKKEY} * \nocite{*} for test usage * \bibliographystyle{abbrv, alpha, ...} "Tell them what you're going to tell them, tell them, then tell them what you've told them" ===== Introduction/Motivation ===== * The opening paragraphs can set the reader's attitude to the whole manuscript, so begin well. [Zobel] * Not much more than 10% of the complete manuscript (about 0.5--1 page) * Introduction usually composed of three parts: === The topic === * Starting like "In this manuscript, ..." indicates missing context. * Funnel: * start broadly, e.g. "In sequence analysis, ..." * get more and more specific very quickly, e.g. sequence analysis -> comparison of sequences -> alignments -> global vs. local === Actual content === * Now you can go ahead like "In this manuscript, ..." * as cursorily as possible (to not loose the reader due to too many details) * as detailed as necessary (to be informative and comprehensible) === Structure === * Structuring a manuscript well can be difficult. Communicate the structure/logic to the reader. * short paragraph (separated from above by \medskip) * one sentence per chapter * not too monotonic, connect sentences * Brief summaries at the start and end of each section * Sentences linking one section to the next E.g.: "Together, these results show that the hypothesis holds for linear coefficients. The difficulties presented by non-linear coefficients are considered in the next section." ===== Conclusions ===== "tell them what you've told them" ... and more: * Summary * Impact * Open questions / future work ==== Mathematics ==== * Variables in //italics// ($ $). * Do not use the same variable name for different things. * Avoid sub- and superscripts. * Do not begin sentences with variable names. * Repeat the type of variable when using a variable, but be careful with the placing of the variable. E.g.: "... a sorted list of numbers sampled from the given set S" versus "... a sorted list S of numbers sampled from given set" * Not every piece of math is an equation or formula. Maybe it is just a term. * Definitions, Theorems etc. * should be self-contained * usually contain an (implicit) "Given..." part followed by a "Then ..." part * should be put into context / introduced / explained. Do NOT just rephrase a complex formula in words, but explain the meaning. * Beautify: * Take care of the spacing, e.g.: +x (sign) versus + x (addition) * Take care of line breaks. * Do not use 'x' or \times as multiplication symbol. Use \cdot or just a space. * paratheses in different sizes: \left( \sum ... \right) * x_1 + x_2 + \cdots + x_n * x_1, x_2, \ldots, x_n ==== Checklist ==== * Did you write concisely (no excessively long sentences; no redundancy)? * Are paragraphs used reasonably? * Did you use some variation in the sentence structure and use of introductory phrases? (Phrasebank) * Are the title and headings consistent with the content? * Is the style and wording of headings and captions consistent? * Do all headings have maximum or minimum capitalization? * Have all terms been defined? * Were all new terms introduced in italics (\emph)? * Has terminology been used consistently? * Are all variable names in italics (Latex math mode $ $)? * Are variable names used consistently, not for different things, and not at the beginning of a sentence? * Is every abbreviation (abbrv.) stated in full when first used (like in this example)? Is any abbrv. introduced more than once? Is any full statement subsequently used unnecessarily? * Is every abbrv. used less then, say, four times? If so, can it be removed? * Have bold and italic been used logically? * Are any words hyphenated in some places but not in others? * Do the parentheses match? Are they necessary? * Are the graphs/figures all the same size? Is similar font size used in graphs/figures? * Are figure sources explicitly cited in the figure caption (Figure reprinted from [x].)? * Are all figures, tables, and algorithms referenced at an appropriate place in the text? * Are captions of figures and tables as well as definitions, lemmas, theorems etc. self-contained? * In the references, has each field been formatted consistently? (Automatically done by Biblatex.) Is capitalization correct, e.g., are acronyms or names capitalized (embrace by {} in your bibfile)? Are journal and conference names abbreviated in the same way? Is the style of author names consistent? (Automatically done by Biblatex.) Has a sufficient and consistent set of fields been provided for each reference of the same type (e.g., "location" for books, "last access" for websites)? * DO USE A SPELL CHECKER as a very last step before submitting the manuscript.