Don’t mix content and style

A general principle in typesetting — be it on (digital) paper or the web — is to separate content and style. Separation is commonly achieved through the use of a markup language, which is a system of document annotations. These annotations declare portions of text as title, section headings, or list items but crucially, they are agnostic to what this means visually (e.g., <bold>text</bold> instead of text). There are several advantages to this approach but I’ll only briefly name three of them here:

1. Focus on writing. It seems that a common form of procrastination for many writers is making a document pretty. Adding a newline here or a manual line break there, moving a table just two pixels to the left, etc. When writing a markup document in a plain text document it let’s you focus on the content rather than the style.
2. Swiftly adjust the style. If your paper is rejected and the next target journal prefers a different flavor of APA style, there is no need to touch your writing. As a simple example, I recently submitted a paper to a journal that asked me to collect all figure captions at the end of the document on one page rather than printing them below the corresponding figures. Because my captions were declared as such, I left the text unchanged (captions below the figures) and simply changed the option controlling the captions’ position within the document.
3. Write plain text files. Once you move to writing in plain text files, you open yourself up to a whole new world of very helpful tools to facilitate your writing and collaboration, such as dynamic documents or the version control system git, but that’s a topic for another blog post.

Learn Markdown

Am I suggesting you replace one evil with another? Not learning APA style requires learning a whole new language? No, Markdown is intended to be as easy-to-read and easy-to-write as possible. The following is an excerpt from the APA example manuscript written in Markdown.

# Methods
## Participants
Younger adults (14 women, 10 men, $M_{age} = 19.5$ years, age range: 18–22 years) were recruited with flyers posted on the Boston College campus. <!-- Add flyer to appendix! -->
Older adults (15 women, nine men, $M_{age} = 76.1$ years, age range: 68–84 years) were recruited through the Harvard Cooperative on Aging (see Table 1, for demographics and test scores).[^p]

[^p]: Analyses of covariance were conducted with these covariates, with no resulting influences of these variables on the pattern or magnitude of the results.

Without knowing anything about Markdown, it should be easy to guess what the annotations mean. # declare hierarchical section headings, <!-- and --> envelope comments, and [^p] adds a reference to a footnote. As you can see, Markdown is easy to learn and will quickly save time in manuscript preparation. The only thing that may be scary at first are the equations enveloped by $. Equations are written in the powerful, yet, fairly simple equation syntax used in LaTeX. Although LaTeX is widely used to write entire manuscripts (not just equations), it is not very popular in the field of Psychology. I suspect that the neglect is largely due to its complexity and long learning curve, which I find rather deterring myself. Both seem to outweigh the advantages of the system when it comes to handling citations and cross-references or typesetting large documents, complex tables, and equations which are rare in the average Psychology paper. That is why I like the idea of using Markdown as a simple interface to harness the power of LaTeX without having to write or know much about LaTeX.

Use a reference manager

If you are not already using a reference manager such as Zotero, I strongly suggest you start doing so. Reference managers are like iTunes for your literature; they help you search, download, and organize papers. Most importantly, with a few clicks you can export a collection of references you need for a paper into a .bib-file. Once your references are in a .bib-file that resides in the same folder as your Markdown-file, you can easily add citations to your Markdown document. Each reference has a unique handle, e.g. lewandowsky_computational_2011, which you can use in Markdown. @lewandowsky_computational_2011 creates an in-text citation; [@lewandowsky_computational_2011] creates a citation in parentheses. Everything reference-related, such as in-text citation and the reference section, will be taken cared of automatically.

Let R take care of the rest

To turn your Markdown file into a polished APA manuscript, you need to set a few options and then create a .pdf-file. Both could be done manually but the way I do this is by using the text editor RStudio (a text editor for R, but you literally need no knowledge about R to do this) and papaja, the R package I’m developing with Marius Barth. In turning your Markdown into a .pdf-file there are intermediate steps and software involved that are really not important to know. RStudio lets you do all of this by the click of a button. As a side note, if you use R for your analyses, you can embed the analysis code into your document and insert statistics, figures, and tables on the fly while creating your manuscript. This is what is called a dynamic document (Xie, 2013) and the topic of a future blog post.

Requirements

If you want to try writing a manuscript in Markdown, you need to install a couple of things:

• R (2.11.1 or later)
• RStudio (0.98.932 or later)
• A TeX distribution (2013 or later; MikTeX for Windows, MacTeX for Mac, or TeX Live for Linux)

Make sure you install the complete—not the basic—TeX version and if you are on Ubuntu 14.04 you need a couple of extra TeX packages. Finally, install the development version of papaja by opening RStudio and copying the following into the R console:

install.packages("devtools")
devtools::install_github("crsh/papaja")

New documents

Once you installed papaja you can create an APA document through the menus in RStudio (File > New File > R Markdown). If you take the time to explore the menu a little bit you will find that Markdown can be used to create a range of different documents like slides or HTML-files. The new text file will contain a document header enveloped by --- followed by the body of the text. There will be some scary looking R stuff following the header; feel free to delete all of it. To preview your manuscript click the Knit-Button. If you click on the question mark next to it, you can get help regarding Markdown in case you get stuck. Also, a look at the papaja-example document may be helpful. All you need to do now is fill in the meta-information, e.g. authors, title, and abstract in the header of the document, start writing, and stop worrying about APA style.