# Technical Hints for Writing Papers

*This chapter is based on the notes [2022-07-19_Evaluation_PaperWriting.pdf](../../course_notes/2022-07-19_Evaluation_PaperWriting.pdf)*

## Paper Structure

- Abstract
- Introduction + Related Work
- Concepts
- Evaluation
- Conclusion
- Statements (Data Availability, Funding, Acknowledgements)
- References

## Paper Content

- See review criteria
- Tell the whole story in the introduction, rest is detail

## Methodology for Paper Writing

> [P.R. Halmos](http://www.stat.rice.edu/~riedi/Halmos.html):
>
> There is no recipe and what it is.
>
> The basic problem in writing mathematics is the same as in writing biology, 
> writing a novel, or writing directions for assembling a harpsichord: 
> the problem is to communicate an idea.
>
> To do so, and to do it clearly, you must...
>
>    * have something to say,  
>    * have someone to say it to,  
>    * organize what you want to say,  
>    * arrange it in the order you it said in,  
>    * write it, rewrite it, and re-rewrite it several times,  
>    * be willing to think hard about and  
>    * work hard on mechanical details such as diction, notation, and punctuation.
>
> That's all there is to it.

### Psychological tricks:

- empty-page effect
- divide and conquer
- small steps, incremental
- start, even if you think the outcome will be marginal 

### Approaches to writing:

- Treat writing a paper like programming/software development
- Source code is precious, should be of high quality and maintenable
- Consider teamwork / shared code

Consequence: Source code of paper should be:

- well readable: structured, organized
- minimal: refactored, avoid repetitions with macros, remove unnecessary comments

Examples:

- Do not write 'CPAchecker', but use `\newcommand{\cpachecker}{CPAchecker}`.
      If you change typesetting to `\textsc{CPAchecker}`, only single location
      must be changed
- Do not print numbers of experimental data in table and repeat them in text,
      but use `\newcommand{\correctAlarmsCpachecker}{238}`.
      Avoids typos and inconsistencies (also makes automation easier).

Source: [Our wiki](https://gitlab.com/sosy-lab/doc/-/wikis/Writing-Papers-(Technical))

More sources:

- [Armando Fox: Armando's Paper Writing and Presentations Page](https://people.eecs.berkeley.edu/~fox/paper_writing.html#anchor226242)
- [Donald E. Knuth, Tracy Larrabee and Paul M. Roberts: Mathematical Writing](http://tex.loria.fr/typographie/mathwriting.pdf)
- [Joel E. Cohen: To A Young Scientist](http://www.sigplan.org/Resources/Advice/Cohen)
- [Mary-Claire van Leunen and Richard Lipton: How to Have Your Abstract Rejected](http://www.sigplan.org/Resources/Advice/VanLeunen-Lipton)
- [Mark Wegman: What it's like to be a POPL referee; or how to write an extended abstract so that it is more likely to be accepted](http://doi.acm.org/10.1145/14947.14955)
- [P. R. Halmos: How to Write Mathematics](http://www.stat.rice.edu/~riedi/Halmos.html)
- [Simon Peyton Jones: How to write a good research paper, give a good research talk, and write a good grant proposal](http://research.microsoft.com/~simonpj/papers/giving-a-talk/giving-a-talk.htm)
- [William Pugh: Advice to Authors of Extended Abstracts](http://www.sigplan.org/Resources/Advice/Pugh)


## Text editing

- (at least) every sentence on new line
- avoid changing line breaks (do not auto-wrap lines)
- use short lines
- avoid tabs, use spaces
- commit everything to repository that is required to build the project
- also commit the bibliography file (`main.bbl`)!
- always check diff before push

Example diff to show how short lines are helpful: What is the actual change?

```diff
- To increase the reliability of these results, validators like \textsc{CPAchecker} \cite{CPACHECKER}, \textsc{UAutomizer} \cite{UAUTOMIZER2013}, and \textsc{MetaVal} \cite{MetaVal} use witnesses to reverify programs wtih desirably less effort by trying to reduce the state space by strengthening the used analysis with
+ To increase the reliability of these results, validators like \textsc{CPAchecker} \cite{CPACHECKER}, \textsc{UAutomizer} \cite{UAUTOMIZER2013}, and \textsc{MetaVal} \cite{MetaVal} use witnesses to reverify programs with desirably less effort by trying to reduce the state space by strengthening the used analysis with
```

vs.

```diff
To increase the reliability of these results,
validators like \cpachecker~\cite{CPACHECKER},
\uautomizer~\cite{UAUTOMIZER2013}, and \metaval~\cite{MetaVal} 
use witnesses to reverify programs
- wtih desirably less effort
+ with desirably less effort
by trying
to reduce the state space by strengthening the used analysis
with
```

## Comments

- \% Text that may be used in the future
- \%\%\% db: Explanation by Dirk Beyer for co-authors 
- Each comment starts a new line

## Macros

- `\newcommand{..}[#args]{..}`
- Never use `\def`! Silently overwrites existing macros

## Writing Style

- avoid ambiguity with symbols:
    'a set S of states', **not** 'a set of states S'.
    With the latter, S could also be a state.
- 'iff' in conditions (theorems), 'if' in definitions

### Spaces and Periods

- french spacing: 'D. Beyer' -> D. Beyer (single space, not larger)
- paragraphs: `\noindent`, `\smallskip`, `\medskip`, \bigskip`
- hair space between quantity and unit: 33\\,GB (best solved with siunitx)

![Example for 33 GB with normal and hair space](10-TechnicalWriting/examples.png)

- use short symbols: 'the state~s', 'for all\~i'
- citations:
    - Reference is **not** part of sentence, never used as object in sentence. Removing the reference may not destroy the sentence. 
        Bad: "[3] says ...", "as described in [4]"
        Good: "as described by Smith [4].", "as done in HCI [5]"
    - Always use non-breaking space `~\cite{...}`
    - Avoid "et al."

## Types of Hyphens and Dashes

* Hyphen: Conjuncts words
* En-dash: Minus and range
* Em-dash: Separation of thoughts, insertion

![Examples for Dashes](10-TechnicalWriting/examples-dashes.png)

## BibTeX

- Use proper names for entry keys
    * R-textbook
    * Fool-Name, Author-Name + Year
    * Conference
    * Best: Memorizable abbreviation
- Entry data should be in consistent style and formatting
- Use 'annot' field for short explanation why paper is relevant

## Repository Organization

- Start repository as soon as serious work on topic exists (e.g., whiteboard screenshot)
- Commit each document
- Main source file: `main.tex`
- Split large documents into sections. For example: `main.tex`, `abstract.tex`, `intro.tex`, ...
- Sub directories:
    - `archive/`
        - `2021-03-02_CAV07-submission.pdf`
        - `2021-07-05_CAV07-published.pdf`
        - `2021-07-05_CAV07-Copyright-Form.pdf`
        - `2021-05-05_CAV07-rebuttal-answer.txt`
    - `paper/`
        - `main.tex`
        - ...
    - `talk/`
        - `main.tex`
        - ...