This project is created by members of the Yale Political Science Department for best practices in running surveys on Qualtrics and with Amazon Mechanical Turk workers.

The SOP sources are organized by chapters. Each chapter has its own folder containing all files it needs.

To create a new chapter, copy one of the example folders:

• example-latex if you're writing in LaTeX,
• example-md if you're writing in Markdown,
• example-rmd if you're writing in Rmarkdown,

and change the folder's name to something good. Now you can start writing the chapter. When the chapter is ready to be included in the SOP, add the chapter's name to the sop.yml file.

The SOP can be compiled into PDFs or HTMLs. Everything is done by an automated build system using Make, Pandoc and R. You might need to install some software to make it run (see the dependencies section).

To build everything (i.e., the complete PDF and HTMLs for all chapters), simply run the following command in the top folder:

make

The result will end up in bin/sop.pdf and bin/html/.

You can also build parts of the SOP (e.g., when you're writing on a chapter and want to see how it turned out):

# Compile only the PDF (i.e., `bin/sop.pdf`)
make pdf

# Compile PDF chapters seperately (they end up in the `bin/pdf-chapters/` folder)
make pdfchapters

# Compile only HTMLs
make html

# Compile PDF and HTML for chapter "NAME" only
make all-NAME

# Compile PDF for chapter "NAME" only
make pdf-NAME

# Compile HTML for chapter "NAME" only
make html-NAME

Finally, you can remove all the compiled files with:

make clean

To compile the complete SOP, you'll need:

• UNIX-like enviroment including make
• pandoc and pandoc-citeproc
• R with packages rmarkdown and yaml
• A TeX distribution with pdflatex and bibtex

However, it's possible to edit and build single chapters without most of these dependencies.

To check if all software is installed, run the following command in the top folder:

./check_macos.sh

All dependencies can be installed by Ubuntu's package manager:

sudo apt-get install build-essential pandoc pandoc-citeproc r-base texlive

Install the required R packages with:

Rscript -e "install.packages(c('rmarkdown', 'yaml'), repos='http://cran.r-project.org')"

It's slightly tricky to build the complete SOP on Windows. It might be smarter to focus on single chapters and let someone else do the final build. It should, however, be possible with some effort.

First, you need to install a UNIX-like enviroment. There's several alternatives: Cygwin, MinGW, Mingw-w64 and WSL.

In most cases, the UNIX enviroment you installed includes make. If not, you need to install it. See, e.g., the GNUwin32 project.

See Pandoc's website on how to install pandoc and pandoc-citeproc.

R can be downloaded from their website.

Finally, the two main TeX distributions for windows are MiKTeX and TeX Live.