Style guide

[joelwross]

Standardize language and writing style, as well as text formatting:

(Joel's notes 05/31):

• When to use bootstrap alerts as callouts?
• Favor "programming" over "coding"
• Use of pronouns (avoid "we"). But should we be using "I" to describe 2 authors? (Mike's note 8/23)
• Should git, R, etc be in code blocks? Italicized?
• Should example output be produced using R chunks (separate block), or written inline as comments? (TODO: figure out how to format output blocks differently than non-output blocks!)
• Table styling
• Should the first letter in a comment be capitalized (i.e., # my comment... v.s. # My comment...)?(Mike's note 8/23)

[mkfreeman]

Additional standardizations:

• Segments in code-blocks that should be replaced (i.e., git add file-name v.s. git add FILENAME)
• Optional arguments (always using [options] ?)
• Maybe: put in a command prompt for one line pieces of code (start terminal lines with $, one line R statements with >)?
• Could it be helpful to have a standardized vocabulary associated with each chapter?
• Standardize header depth (segments like 4.3.2.1 seem unnecessary / distracting)

We could/should include a description of the standardized syntax (i.e., how to read the book) in an Introduction chapter.

[joelwross]

I stopped including command prompt symbols in code blocks after watching multiple students get confused or just slowed up by copying and pasting the prompts when following guides.