What is the decision process that leads to R Markdown or some other document creation strategy?

[jeromyanglim]

What is the decision process that leads to R Markdown or some other document creation strategy?

[jeromyanglim]

• What type of document needs to be produced?
  • slide show, web page, paper based
  • degree of complexity (e.g., need for bibliographic system, cross-referencing, table of contents, etc.)
  • degree of control over formatting required
  • standardised document (e.g., journal article; thesis; ...)
  • interactive tools for exploring data
• Whether to use a binary format or a plain text format?
  • binary formats: e.g., word processors, presentation software
  • plain text formats: e.g., HTML, LaTeX, various types of markup (e.g., Markdown)
  • Within plain text: ease of manual editing
• Distinction between source format and output format
  • For example, PDFs are rarely manually edited, but are easy to generate from LaTeX
• Some document formats more readily permit conversion to multiple output formats to permit multiple uses
  • this also relies on conversion tools.
• Whether to use a reproducible document format?
  • Degree to which analyses are central to document
  • Degree to which collaboration requirements permit use of such a format
• R Markdown
  • Homework for statistics subjects
  • Preliminary analyses of a dataset for self and to share with colleagues
  • Preparing basic web posts
  • It is mainly designed for screen based presentation. This is an advantage for informal analyses where worrying about page breaks and keeping content within margins are a nuisance.

What is the formality distinction?

• Formal documents generally hide console input.
• Formal documents generally require greater polish to graphs, tables, and text.
• Formal documents often have to comply with specific style guidelines.
• Formal documents are typically circulated to a broader audience with a variety of background knowledge. This contrasts with informal documents which are often for yourself or your colleagues. Formal documents may need to stand alone and are often important.

Elaborate on the page versus browser metaphor?

• It is possible to print webpages, and it is possible display word processing documents in a web format. Thus, the distinction is a little bit fuzzy.
• Nonetheless, there is a distinction in the source information. In LaTeX, there are many options that control how the page is organised on a page. The page size is set, figure and table placement is designed to ensure that such objects display in desirable ways on printed page.
• In contrast, the browser metaphor is a continuous stream, often the width of the page can vary with the width of the browser, content is one long continuous stream. The page in a browser is organised into chunks of content that can be of variable length.

Background

The broad motivation for knitr, R Markdown, and other tools is the desire to create a trustworthy document.
In academic and industry settings we create a documents that take a variety of forms.

We are immediately confronted with the issue of what format we should use to create the document.