As with the discussion on workflow, this article provides strategies for collaboration with Rmarkdown within Cabinet Office analytical teams and is not specific to the deckhand package. In particular it discusses how to collaborate on writing the narrative elements of Rmarkdown with those who do not have or use R such as managers or policy colleagues.
The general approach discussed in this article is as follows:
- Develop a draft of your report
- Set up a Google Sheet, stored in the relevant corporate area of the Drive, with at least three columns:
page_id,page_title,page_text. - Share an HTML/PDF version of the draft report with colleagues
- Work with colleagues to agree titles and narrative text for each page.
- Export the Google Sheet as CSV and save in the same folder as the Rmarkdown file
- Import the CSV to your Rmarkdown
- Insert the text and titles to the relevant pages
This approach will then allow you to iteratively develop the R code elements of the report, while multiple people (including yourself) can edit and comment on the narrative elements of the report together. When there is an update to the text you can simply re-download the Google Sheet and re-render the report.
Setting up the Google Sheet
You should set up a Google Sheet to store and edit the narrative text elements of your slides such as the .title and .maintext elements of each page. If you have pages that make use of the .secondary-text element or have additional narrative boxes on the page then ensure you have a sufficient number of columns setup and named.
Here is an example sheet:
| page_id | page_title | page_text |
|---|---|---|
| summary | Our analysis shows that X causes Y | Lorem ipsum dolor sit amet, enim sem. Vel elementum mi phasellus maximus eros nibh aliquam eros in montes mauris. Nullam leo, nulla imperdiet, ferment... |
| page1 | A and B have different outcomes | Lorem ipsum dolor sit amet, non, curabitur iaculis vitae volutpat eros et ac. Sed venenatis, sed pellentesque vitae justo eget. Vitae mus congue ipsum... |
| page2 | A's outcomes are due to C | Lorem ipsum dolor sit amet, mauris laoreet proin! Iaculis, aenean luctus at, duis, mollis, ac. Ullamcorper pulvinar, integer sapien ac ornare, sed eui... |
Working with Google Sheets and Rmarkdown
Having set up the Google Sheet we can download and save the Sheet as a CSV file in the same folder as the Rmarkdown report.
Add the following to your report’s setup chunk to read in the sheet and set up vectors that make it easy to access the narrative elements a later stages of your report.
page_narratives <- readr::read_csv("google_sheet.csv")
page_titles <- purrr::set_names(
x = page_narratives$page_title,
nm = page_narratives$page_id
)
page_text <- purrr::set_names(
x = page_narratives$page_text,
nm = page_narratives$page_id
)You are then able to simply call the title and text for a page by taking the relevant vector and using the relevant page_id to select the specific text of interest.