writing.qmd

# Writing

Writing is a key part of academia. We communicate our ideas via manuscripts, books, reports, grant proposals, and blogs. We also make presentations and poster to disseminate our findings. Here we review some tools and tips for writing and presenting our work.

## Software for writing

Though Microsoft Word/PowerPoint and Google Docs/Slides can be convenient, they do not make reproducible outputs. A reproducible alternative is [Markdown](https://daringfireball.net/projects/markdown/), which is a markup language that allows you to write [plain-text](https://en.wikipedia.org/wiki/Plain_text) in a [text editor](https://en.wikipedia.org/wiki/Text_editor) and include special syntax to control formatting. Markdown files get passed to Pandoc, which can process the syntax and convert the file to a formatted output file such as HTML, PDF, or DOCX. This contrasts with Word/PowerPoint where the formatting is shown to you in the app (What You See Is What You Get or WYSIWYG).

A key benefit of Markdown is that you can see exactly what syntax is generating the output. This concept was pushed further with [R Markdown](https://rmarkdown.rstudio.com/) and [Quarto](https://quarto.org/). These packages allow you to directly embed R (or Python, Julia, or Observable in Quarto's case) code into the Markdown document. When processing the R Markdown or Quarto file, an additional step runs the R code and embeds the results into a Markdown file before it is passed off to Pandoc. Thus, you have a file with both Markdown syntax showing the formatting and R code showing the calculations. It's totally reproducible!

Markdown syntax is pretty simple. Here are some quick examples:

| Code | Output |
| ---- | ------ |
| `_italics_` | _italics_ |
| `**bold**` | **bold** |
| `~~strikethrough~~` | ~strikethrough~ |
| `^upper^case` | ^upper^case |
| `~lower~case` | ~lower~case |
| `* bullet` | • bullet |
| `# Header 1` | **Header 1** |
| `[link](https://dogcog.unl.edu)` | [link](https://dogcog.unl.edu) |


Check out the [Markdown Guide](https://www.markdownguide.org/) for a full reference guide on Markdown syntax. It's quite powerful and can include figures, tables,  [bibliographies](#bibliographies), cross-referencing, footnotes, math symbols, etc. And Markdown can be used to create documents, books, presentations, and webpages.

### Bibliographies

Citing our sources requires keeping track of all of the articles, books, websites, and dissertations that we use as resources. [Zotero](https://zotero.org) is a "free, easy-to-use tool to help you collect, organize, annotate, cite, and share research". There are two key functions of Zotero.

### Source organization {-}
First, Zotero organizes all of your sources. It keeps track of authors, titles, DOI, URLs, etc. so you can search through your "collection" to find sources. Critically, it also stores PDFs of each source, so it is a great way to organize PDFs.

How do you get sources into Zotero? It's easy. There are extensions for all of the major web browsers. When installed, there is a little button that, if you press it while on a source's webpage, will automatically extract the relevant meta-information (author, year, title, publisher, DOI) from the page and save a PDF (if available). You can also import meta-information either from other bibliography software (e.g., EndNote, Mendeley) or from a file with that information formatted appropriately.

Within Zotero, you can create 'collections' or subfolders that include specific sources relevant to a particular topic. So instead of sorting through my 10,000 (!) sources, I can go straight to the `dog_inhibition` collection to see the relevant sources. In addition, you can share collections with other Zotero users either directly via their usernames or you can create [Zotero Groups](https://www.zotero.org/groups/) to share and collaborate on collections of sources.

### Formatting bibliographies {-}

Another key feature of Zotero is that it can automatically format references to your sources. For instance, if you have a collection full of sources for a paper, you can export those references, choose a formatting style, and Zotero will create a completely formatted bibliography for you. So you don't have to remember if APA style italicizes the volume number or uses a colon or comma after the issue number. There are thousands of [style files](https://www.zotero.org/styles) already created for most journal styles. This is especially useful if you need to quickly change styles---it just takes selecting a different style type.

What's more, you can even use special code to enter sources directly in your document as in-text citation. When you do this and compile the document the in-text citations and the bibliography are automatically formatted to the style you choose. If you add or remove sources, the bibliography is automatically update. It's amazing! No more typing out bibliographies. Use Zotero.


## Writing lots and well

Before we get to specific types of writing, it's important to remember that writing isn't easy for most of us. Writing is hard. Which means that we need to write a lot (meaning often) and revise a lot (meaning much of the writing). Motivating writing can be difficult, so folks often use strategies such as scheduling a certain amount of time each day to write. Or require yourself to write a certain number of words each day. Find a good time of day that works for you, and reward yourself after writing with something that you enjoy.

But writing a lot isn't enough. You also need to write well to effectively communicate. First, that means know who your audience is. Are they novices who know nothing about your topic? Or are they experts in this area? I usually assume my audience is smart people who know nothing about my work.

The two key things to keep in mind when writing are to **write simply** and **write concisely**. Writing _simply_ means using simpler words that more people know. 

* Avoid using jargon or thesaurus words. 
* _Use_ simpler words instead of _utilizing_ more complicated ones.
* Write short sentences. Longer sentences with lots of phrases are hard to parse. Split long sentences in two.
* Imagine your grandparent is reading your text. Would they understand? If not, simplify.
* Check your readability with [readability checkers](https://readable.com/text/).

Writing _concisely_ means using as few words as possible to convey your meaning.

* Avoid unnecessary phrases that convey no real meaning. Here are two big ones that I cut out every time I see them.
  - "In order to" can just be "To" over 90% of the time.
  - "Research shows that" can also almost always be removed. Just state what the research shows!
* Avoid passive voice when possible. Active voice tends to use fewer words and is clearer.
* Read each sentence separately and check whether each word is necessary. Be brutal and cut anything that is not necessary to convey your meaning.

## Journal articles

The primary currency of productivity in the behavioral sciences is publications, with a strong emphasis on peer-reviewed journal articles. The expectation of the lab is that most of the work that we do should be published in journals. Even if the results don't turn out as we expect, if we don't have methodological errors, we will aim to publish our results in journals. So the expectation is that people who take the lead in projects will write up the work in journal article form. Publishing journal articles can take months or years, so even after you leave the lab, we need your help in writing, revising, and responding to reviewer questions.

There are two ways that lab members' contributions to projects are signaled in journal articles: authorship and acknowledgments. Authorship signals a substantial contribution to the project (see [Authorship](#authorship) section). Assistants who contribute less substantially are highly valued and appreciated and included in the Acknowledgment section of the paper. If you are interested in being an author on a paper, contact Jeff early to discuss ways that you can contribute to the paper in way to merit authorship.


### Journals

Before the writing process gets started, it is useful to think about what potential journals we would want to submit to. We want to think about this early because it can greatly shape the scope, direction, and length of the paper (especially the Introduction and Discussion). Talk to Jeff about potential journal venues. In general, Jeff has a preference for [diamond open access journals](https://en.wikipedia.org/wiki/Diamond_open_access), which are journals that publish papers without charging authors to publish or readers to access. These are often society-governed journals run by academics instead of for-profit publishing companies that have [higher profit margins than the major tech companies](https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science) and are built on the free labor that academics provide through peer review. Other journals may be appropriate for some papers, but Jeff has a strong preference for open access options and [not to publish in Elsevier journals](https://science.thewire.in/the-sciences/why-i-wont-review-or-write-for-elsevier-and-other-commercial-scientific-journals/).

Some of our favorite diamond open access journals include:

* [Animal Behavior & Cognition](https://www.animalbehaviorandcognition.org/)
* [Comparative Cognition and Behavior Reviews](https://comparative-cognition-and-behavior-reviews.org/)
* [Human-Animal Interactions](https://www.human-animal-interaction.org/human-animal-interaction-bulletin/)

### How to write a journal article

Here are some tips for writing journal articles.

#### Things to think about before writing {-} 

- Why are you writing a scientific article? 
- What will be the scope of this article?
- Who is your audience?
- Where will you submit the article?
- Who should be a co-author, and what will be their roles?
- How will you collaborate on writing?


#### The structure {-} 

Research articles are fairly formulaic. They do not need to be especially long to get your point across. In fact, the fewer words required to communicate your point, the better. My own view about the structure of a paper fits nicely with that of Claus Wilke, and he has some very helpful pointers for [writing a paper in four easy steps](https://serialmentor.com/blog/2013/8/29/writing-a-scientific-paper-in-four-easy-steps). I usually write them in the order Methods, Results, Discussion, Introduction, Abstract (or switch Introduction and Discussion).

*Abstract*

- Abstracts can be difficult to write. Write your abstract for a high-school educated person with no knowledge of your research program who will not read the rest of your paper. Hook them, so that they want to!
- Some journals and fields have specific subsections to fill out: Background, Objective/Aim, Methods, Results, Conclusions. These structured abstracts can be a useful templates even if the journal does not require it, because they generally improve readability [@Hartley.Sydes.1997;@Hartley.2004]. 
- Do not ever say "X, Y, and Z are discussed". Write your abstract in active voice as much as possible and give your conclusions rather than just say some topic is discussed.
- Feel free to copy and paste sentences from the rest of your paper (since this is likely written last), but know that you will likely have to heavily edit them to make them accessible to your audience.
- After writing a draft, consider running it through a readability scorer to see how accessible it will be.

*Introduction*

Introductions should be relatively short---they do not need to be full literature reviews if you are writing an empirical paper. Quickly cover the relevant literature.

- First paragraph
    * Try to start with a specific, catchy example that gives the reader a visual experience to remember during the rest of the paper. Check out some of our previous work for examples (e.g., [Duque et al., (2020)](https://decisionslab.unl.edu/publications.html#y2020) or [Goh et al., (2020)](https://decisionslab.unl.edu/publications.html#preprints)).
    * Next, try to expand to explain the big picture very quickly. What is the big question that this paper addresses, and why is it important?
- Middle paragraphs
    * In the next few paragraphs, unroll a more specific story that conceptually motivates your project and places it in the theoretical foundation of your area.
    * Move from background literature to the focus of your paper.
- Final paragraph or two should be about the current study
    * Describe your overall research question(s).
    * Give a short description of your approach to answering the research questions.
    * End with your hypotheses and/or predictions.

*Methods*

- Participants/subjects
    * Describe the source and demographics of your participants.
    * Describe *when* your data were collected.
    * Describe why and how many participants/subject were excluded.
    * Give information on IACUC/IRB approval for the project.
- Materials
    * Describe the materials, apparatus, location.
    * Often including a diagram of the experimental set-up is useful here. This can be either an image (remember, images of animal experiments must be vetted by the IACP before being made public) or a graphic you create (e.g., preferably an SVG graphic created in [Inkscape](https://inkscape.org)).
- Procedure
    * It is usually best to describe the full procedure in detail here. It is easier to cut extraneous details than have to go back later and remember details to add.
    * This will likely be the longest section of the Methods.
    * Don't forget to include information on training/warm-ups, etc.
- Experimental conditions
    * Sometimes it's nice to have a separate section describing the experimental conditions, especially if they are detailed. But sometimes it makes sense just to move this as a subsection of Procedure.
    * Again, illustrations (either images or graphics) of experimental conditions are very helpful. I recommend adding them whenever possible.
    * Use good, descriptive names for experimental conditions (such as ostensive and non-ostensive rather than treatment and control) and use them consistently through the paper
- Data analysis
    * Cite R and the R packages that you use (this is done easily in R Markdown with the `{papaja}`).
    * Describe where data, code, and supplementary materials can be found (e.g., [Open Science Framework](https://osf.io))
    * If applicable, describe that the document is a reproducible document written in R Markdown.
    * Describe the statistical analyses used. I find it useful to walk through the R script and describe what happens to the data.
    * If using Bayes factors, give a short description of what they mean, the thresholds that you use, and the priors (if needed). If you are estimating them from BICs, include the formula $e^{(BIC_{null}-BIC_{alernative}) / 2}$. Good citations include @Wagenmakers.2007 for BFs generally and the BIC formula and @Wagenmakers.etal.2018 for thresholds.

*Results*

- Each major result/hypothesis should have its own section (or at least paragraph). Start with building the figure for the section, then write a paragraph about it.
- Within each section, start with a reminder of what the hypothesis/aim is, followed by a very brief description of how the data were analyzed.
- Then move into describing the results, using objective descriptions of what the statistical test show. Do not draw inferences or discuss conclusions from the data. Describe it in terms of your dependent and independent variables rather than the broader concepts that you are inferring from those variables.
- If using frequentist statistics, give the test statistic, p-value, and effect size. Describe the effects, but **do not use the word _significant_**. 
- For Bayesian hypothesis testing, give the Bayes factor, and describe the results in terms of evidence for hypotheses.

*Discussion*

- Start with a paragraph giving a quick summary of the results.
- Next, spell out the implications of each of your results (in the order presented). This is where you relate the results to your hypotheses, connect them to previous literature, and give conclusions about what they mean and why they are important.
- It is important to include limitations of your study. But don't go overboard here, and don't waste time with sample size as a limitation. It's almost always a limitation.
- Sometimes this is integrated with limitations, but it is nice to point to future directions. What are the next questions/projects that logically follow from this one?
- Finally, it is usually nice to end with a conclusion. This summarizes the findings, highlights the key implications, and ends with a strong conclusion that can be drawn from the study.

*Acknowledgments* 

- Make sure to acknowledge funding sources, assistants who helped collect the data, and people who gave advice or reviewed the manuscript. Notice there are only two `e's in Acknowledgments (in American spelling).

#### Pro tips {-} 
- Keep the presentation of hypotheses/research questions consistent throughout Methods, Results, and Discussion
- To minimize passive voice, read your paper backwards looking specifically for passive voice.


### Before submitting journal articles

There are a few things to consider and do before submitting our papers. We will want to post all data and analysis scripts to publicly via [Open Science Framework](https://osf.io) and/or [GitHub](https://github.com) and include links in our papers. Also, in most cases, Jeff will want to submit a preprint of the article to a preprint server (e.g., [PsyArXiv](https://osf.io/preprints/psyarxiv), [bioRxiv](https://www.biorxiv.org), or [OSF Preprints](https://osf.io/preprints)) before submit the article to a journal. We also need to write a short cover letter and think about potential reviewers to suggest (going through the bibliography is often useful for generating reviewer ideas).


## Grant proposals
### The structure {-}

*Specific aims*

- First paragraph
    * Opening sentence--attention grabbing, relates to funding agency mission, provides general research area
    * Important knowns--establish state of field and set up gap in knowledge
    * Gap in knowledge--obvious extension of knowns
    * Framing gap as problem--gap prevents this step from being taken
- Second paragraph
    * The *long-term goal* of this research program is to... _(addresses agency mission)_.
    * The *overall objective* of this application is to take a major first step towards that long-term goal, namely to... .
    * The *central hypothesis* of this project is tha...  _(directional hypothesis that conveys my best bet as to what explains the phenomenon that I will be investigating. Needs to be objectively testable. Then include why this is best bet (pilot data, etc.))_.
    * The *rationale* for this study is that we expect to... _Why are you doing this? What will be possible after research is completed that is not possible now?_.
- Third paragraph
    * We will test the central hypothesis with the following *specific aims*:
      1. Specific aim 1: _Should be an objective (e.g., identify...) activity with indeterminate end (e.g., study, explore)_.
_Working hypothesis:_ _Testable hypothesis not a ‘look-and-see’_
      2. Specific aim 2: _Working hypothesis:_
      3. Specific aim 3: _Working hypothesis:_
- Fourth paragraph
    * This study is *innovative* because it... .
    * This will provide an important *positive impact* because... _summarize what comes next in Significance paragraph. How will the funding agency benefit?_.
    * Our team is especially *well qualified* to conduct this project because... .

*Background and significance*

- Significance of the proposed research
    * Opening sentences--Despite the widely appreciated magnitude of this problem, there is still a critical gap in the knowledge base that centers on how . As an outcome of the proposed investigations, we expect to have determined the mechanism of/distinguished between/overcome the problem of .
    * The research proposed in this application is significant because .
        - Validate statement of significance with a credible list of benefits
- State of research
- Preparatory work

*Research design*

- Specific aim 1:
    * Introduction. The objective of this aim is to . To attain the objective of this section, we will
test the working hypothesis that . We will test our working hypothesis by using the experimental
approach of . The rationale for this aim is that successful completion of the proposed research will
. When the proposed studies for aim 1 have been completed, it is our expectation that . Such a
finding would be of importance because it would allow, for the first time, the development of novel
and much needed approaches to .
    * Experimental design.
        - Study 1:
            - Justification of need to do the study
            - Approach to be used
            - Method(s) required
            - Key equipment required
            - Numbers of subjects and how these numbers were derived
            - Statistical analysis needed
            - Controls to be performed
            - Replicates that will be needed
            - Detailed expectations
            - Time required to complete the studies
            - Other considerations
        - Study 2: [Repeat]
    * Expected results.
        - Summarize first outcome and its importance
        - Summarize second outcome and its importance
        - Conclude with how outcomes collectively attain the aim’s objective
    * Anticipated problems and solutions.
        - Problem: invalid working hypothesis
        - Solution:
        - Problem:
        - Solution: