Differences

This shows you the differences between two versions of the page.

--- teaching:2024summer:karp:writing [2026/04/29 14:15]
rwittler
+++ teaching:2024summer:karp:writing [2026/04/29 15:49] (current)
rwittler
@@ Line 1: / Line 1: @@
-Content will be back soon...
+====== 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.

Genome Informatics

Differences