Introduction
Recently, we submitted our first manuscript that was entirely written in Rmarkdown. See
\citealt{Roth_2018} for the manuscript. The code that was used to produce this manuscript can be downloaded from
our GitHub repository . Rmarkdown in connection with the version control provided by git / GitHub is a great environment to develop the statistical analyses from the first ideas to the final results. It is also a great way to provide reproducible data analyses to reviewers and readers. However, we felt that the system was not perfectly adapted to a smooth writing process, which includes the writing of the first draft of the manuscript in parallel with developing the statistical analyses as well as the process of developing the final MS from the first draft in collaboration among all the authors (we were eight). In our point of view our workflow had the following shortcomings:
- It is not an environment that makes it easy for co-authors to quickly correct a spelling mistake or to better formulate a bumpy sentence. So I ended up with receiving a lot of mails with comments pointing to some lines within the pdf of the manuscript that should be improved. It took quite an effort to find the corresponding line in the Rmarkdown files to make the corrections and improvements.
- Most coauthors were not comfortable with writing directly into my Rmarkdown files because they were afraid of corrupting the R-code.
- When I worked on the text I ended up switching back and forth between the formatted version of the manuscript (pdf in our case) to read the text and to the Rmarkdown files to make the corrections.
- Handling the references in Rmarkdown-files is a bit clumsy especially if you have a lot of them.
So after this experience I was hoping to slightly improve the writing part of the workflow for the next project. My wish list included the following:
- A workflow that is compatible with R and GitHub but that is also compatible to work with co-authors that won't get passed Word-like editing of text (see also this thread)
- The system should be able to digest figures and tables (preferably in Latex) that are produced from R.
- It should also be possible to have parts of the manuscript which contain of text and numbers that were produced by inline R-code. This is especially handy in the results parts to add some summary statistics without the need to copy past.
- An easy way to search for references on the web and including them directly into the text as well as into the .bib file.
When searching on the web to improve things I came across several sources that mentioned Authorea .
Authorea is a collaborative writing platform for researchers. Authorea has some features that sounded promising to me:
- Authorea can easily be linked with an existing GitHub account.
- Authorea's instant search to locate a reference by author, keyword, or DOI makes it very easy to add references.
- Authorea not only understands (rich) text, markdown, html and latex, these components can also be mixed in the same manuscript which seemed quite unique to me.
- Authorea splits the manuscript into blocks (title, abstract, textblocks, figures, tables) and has a single file (layout.md) that defines how these blocks are grouped together to from the entire manuscript.
Connecting an Authorea document to own GitHub repository
New repository from scratch
- Add new document to AUTHOREA and just write the name of yourrepository as the title of the document. Then setup automatic GitHub integration.
- Go to your GitHub account and the new repository should already be there.