Google Docs as Rmarkdown writing GUI

##Description

#####Summary:

• Use Google Docs for ease of drafting, aiming to output Rmarkdown to increase the use of reproducible documents in science by making it more user-friendly
  • Add some special code signifying what is to be interpreted as code chunks, perhaps make YAML generation more intuitive etc.
• More an idea for Google App Script (Javascript derivative) than an R package
  • Noam suggested this links to RGoogleDrive package dev. (wishlist item 1)
• Fledgling to-do list is at the end

Why Google Docs?

• Free desktop publishing program
• Multi-user collaboration features (even chat)
• Native interface to the popular Drive storage system
• Search functions built in
  • e.g. type a phrase, select it, Ctrl + K to make a link: suggests top 2 search hits, tab + enter to open the webpage
• Fast drafting of documents with a ton of keyboard shortcuts formatting, most elements of which have markdown equivalents
  • e.g. Ctrl + Alt + 1 for top-level header
  • Ctrl + Alt + i for research side-pane including Google Scholar, associated PDF links, citation entry etc.
• Access/'extensibility' through the Apps Script API

Google Docs is designed to be intuitive, so I find drafting a document with it is much easier than writing out Rmarkdown, which feels like writing code by hand where software is already out there to do so.

It'd also be nice to use a graphical editor just to see the document in preparation more clearly during its writing.

Motivation

At a recent Open Data Manchester talk, Carole Goble suggested boosting productivity is the best way to advocate for the open science/RR project (arguably more so than reproducibility per se).

As I noted at the time though, 'open science' isn't in and of itself intrinsically productivity-boosting as Carole seemed to imply. If it is, the benefit emerges both in the long-term and on the scale of scientific community (rather than individuals), i.e. removal of the barrier to entry in carrying out a published analysis for verification/interrogation, often referred to as "accelerating the scientific process".

If anything, doing 'open science' is currently counter to productivity:

• not well-established practices, package/software infrastructure, or examples

• new ways of going about the research process require active dev involvement ∴ productivity gains long-term/community-wide

  

  Carole showed a version of the Gartner hype cycle during her talk, comparing how software/tools development leads to improvements in researcher productivity only after the trough of its development

Advantages and impracticality of Rmarkdown

Rmarkdown will aid productivity since it:

• supports templating (no reduplication of efforts, consistent formatting, TeX control)
• provides the ability to tweak code settings and re-iterate on your own/other people's work (again no reduplication of efforts)
  • with HTMLwidgets and such, potentially even within a display of the document itself
• separates content from styling: text formatting is an afterthought, enabling single-minded focus on content
  • cognitive psychological argument for improved productivity in the act of writing itself
  • ...irony being markdown formatting visually litters content with formatting code (asterisks, brackets etc.) and can become a consideration unlike in GUI writing tools
• diffs on a non-binary file such as .Rmd enable rational change tracking cf. the likes of a Word doc

All these things computational researchers seem to appreciate. However, the barrier to entry — i.e. the need to code for basic functions and put effort into reading/writing markdown formatting — mean the productivity gains won't become apparent for scientists at large without further development work, as I see it at least.

• not really accessible without constant awareness of technical details when writing [R]markdown
• not really 'scalable' in that any reasonably sized document requires an inordinate amount of manual fiddling with formatting code: traditional GUI document editor would be favoured as the only reasonable approach
  • removing these barriers would make reproducible research documents viable on a whole new level, possible with further development, e.g. to prevent the time taken for knitr to compile large documents becoming unwieldy through modularity

With an existing script gdocs2md* it's easy to generate documents with the basic elements of markdown from a Google Doc.

^{* a particularly well-functioning fork of which I've now tracked down and started modifying on GitHub as gdocs2Rmd}

• Google Docs would provide the collaborative and GUI pieces of the puzzle needed for a Rmarkdown setup to compete with the likes of (more aesthetically pleasing/user-friendly but closed source) Office suite, Scrivener etc.
• Noted post hoc that it mimics the Jupyter Project's storage of notebooks (also code documents) on Google Drive.
  • There is at least one existing script to convert IPyNBs to Rmd (by Ramnath)
  • Potential for greater crossover (a button to send your Google Doc to Rmd/JupyterNB?)
• Clarification of aims and feedback on desired use cases would be good.
• The core of the Apps Script code converting a Google doc to a markdown string is here

To do

Some of the following are implemented and/or described in existing forks of gdocs2md

• Switched from script editor to UI menu

• Added chunk syntax ~~~ chunkname, param1="x", param2="y" ... ~~~

  ==> ```{r chunkname, param1="x", param2="y"} ... ```

• Removed hard-coded folder ID and using active doc

• 2 way editing - edits to Rmarkdown should be reflected in Google Docs by some reverse conversion.

• (Option to) view output markdown in browser rather than saving

• Publish to the Chrome web store. NB guidelines state:

  The add-on must be fully functional—it can't be a “work in progress.”

  • see also the guide to developing a plugin on supreetpal's fork

• Way to add linked images (Google Docs by default converts to base64 for ![]({URL})/<img src="{URL}"> style images pasted in, and storing image files locally isn't er, 'scalable'. Hosting will be online anyway

  • add links to image src URL in comments (there are no other attributes in which to store a URL) and mark comments as resolved to hide. Alternatively could delete comment, but the difference seems trivial / misleading.

    See guide to managing comments (with video) on Google Devs site

  • problem arises when an image is deleted during editing: comment remains (comments class accessed through a whole other API). Is there really no way to get the parent (image) element a comment is added to? It's clearly attached in the GUI so must be internally too... Once this is figured out, should programmatically delete any comments not attached to images.

  • To ensure no slip ups (deleting user comments rather than metadata comments), should prefix these special metadata URL comments with {img-src}. Unlikely anyone would be using resolved comments but just in case.

  • Not retrieving deleted comments in the API call here means in the event that images are deleted could just set comment status to deleted too, but the undo capability... just check if parent image element is present upon generating markdown. In other direction delete all {img-src} prefixed comments and upload images from URL

  • NB: for now would need to ask users to add these odd comments themselves when pasting an image. Could look for a on-pasting event to generate it, but all uncharted territory. A UI menu to add images might be an idea, but not so user-friendly 🚧

  • The developers of LucidChart and others have already figured this out. I still think using LINK_URL like this is a bad idea - users might want to apply links to images and should be able to..?

• ...implement the above way to link images

• Extensible way to add languages to objects, e.g. python blocks (different from chunks)

• Extensible way to pass HTML on (markdown can mix the 2)

• Extensible way to add in DOIs - ideally from dx.doi.org links

  • perhaps use in-text like {{cite:#DOI#}} as implemented in this Google Apps script already (or brilliantly {{cite:http://dx.doi.org/#DOI#}}
    • check all links, any dx.doi.org link could be passed as that, either generate citations or pass on to knitcitations

Please add more items to this list if you have ideas.

##Necessary features

1. Save a file as .Rmd, respecting file content
2. Create a syntax to incorporate code chunks from markdown (Google Docs lack code block elements
3. Write appropriate YAML (including a UI with switches?)

##Endorsements and additional suggestions

1. Louis wrote this and endorses all of it.

##Volunteers and work

Louis is working on a prototype that integrates functions created across disparate forks in the gdocs2Rmd repository in line with the goals of the to-do list above, and would welcome collaboration. Ideas for YAML switches (UI menu options) may be helpful.

• Discussion also ongoing at discuss.ropensci.org