The Workflow Idea
During the collaborative writing of an .Rmd (or .Rnw) document, it is important to employ different workflows for computer code and narrative text:
- Code - Collaborative code writing is done most efficiently by following a traditional Git-based workflow using an online repository (e.g., GitHub or GitLab).
- Narrative Text - Collaborative writing of the narrative text is done most efficiently using Google Docs which provides a familiar and simple online interface that allows multiple users to simultaneously write/edit the same document.
Thus, the workflow’s main idea is simple: Upload the .Rmd (or .Rnw) document to Google Drive to collaboratively write/edit the narrative text in Google Docs; download the document locally to continue working on the code while harnessing the power of Git for version control and collaboration. This iterative process of uploading to and downloading from Google Drive continues until the desired results are obtained. The workflow can be summarized as:
Collaborative code writing using Git & collaborative writing of narrative text using Google Docs
trackdown offers different functions to manage this workflow:
upload_file() uploads a file for the first time to Google Drive.update_file() updates the content of an existing file in Google Drive with the contents of a local file.download_file() downloads the edited version of a file from Google Drive and updates the local version.render_file() downloads a file from Google Drive and renders it locally.
For a general overview of the package, see the trackdown-package help page or vignette("trackdown-features") for a detailed description of function arguments and features and vignette("trackdown-tech-notes") for technical details.
Workflow Example
Here a hypothetical workflow using trackdown is described as an example. The actual workflow is flexible and depends on the specific needs and circumstances of a given user and project.
Suppose you want to collaborate with your colleagues on the writing of an R Markdown document, e.g., to prepare a submission to a scientific journal. If you are the most experienced among your colleagues in the usage of R and programming in general, you should take responsibility for managing and organizing the workflow.
Upload File
You create the initial document, for example My-Report.Rmd, and upload the file to Google Drive using the function upload_file():
trackdown::upload_file(file = "Path-to-file/My-Report.Rmd", hide_code = TRUE)
By executing this command, the My-Report.Rmd file is uploaded from your local computer to your Google Drive. By default, the file is uploaded to Google Drive using the same name as the local file (without extension) and saved in a folder named trackdown/.
Note that trackdown adds some simple instructions and reminders on top of the document and, by specifying the argument hide_code = TRUE (default is FALSE), the header code (YAML) and code chunks are removed from the document displaying instead placeholders of type “[[document-header]]” and “[[chunk-<name>]]” (See Figure below). This allows collaborators to focus on the narrative text.
Collaborate
After uploading your document to Google Drive, you can now share a link to the document with your colleagues and invite them to collaborate on the writing of the narrative text.
Google Docs offers a familiar, intuitive, and free web-based interface that allows multiple users to simultaneously write/edit the same document (See Figure below). In Google Docs it is possible to :
- track changes (incl. accepting/rejecting suggestions)
- add comments to suggest and discuss changes
- check spelling and grammar errors (potentially integrating third-party services like Grammarly)