Help brain dump

workflow-help.Rmd

@@ -1,9 +1,15 @@
 # Workflow: Getting help
 
+```{r, results = "asis", echo = FALSE}
+status("restructuring")
+```
+
 This book is not an island; there is no single resource that will allow you to master R.
 As you start to apply the techniques described in this book to your own data you will soon find questions that we do not answer.
 This section describes a few tips on how to get help, and to help you keep learning.
 
+## Google is your friend
+
 If you get stuck, start with Google.
 Typically adding "R" to a query is enough to restrict it to relevant results: if the search isn't useful, it often means that there aren't any R-specific results available.
 Google is particularly useful for error messages.
@@ -13,8 +19,73 @@ Chances are that someone else has been confused by it in the past, and there wil
 
 If Google doesn't help, try [Stack Overflow](http://stackoverflow.com).
 Start by spending a little time searching for an existing answer, including `[R]` to restrict your search to questions and answers that use R.
-If you don't find anything useful, prepare a minimal reproducible example or **reprex**.
+
+## Making a reprex
+
+If your googling doesn't find anything useful, it's a really good idea prepare a minimal reproducible example or **reprex**.
 A good reprex makes it easier for other people to help you, and often you'll figure out the problem yourself in the course of making it.
+There are two parts to creating a reprex:
+
+-   First, you need to make your code reproducible.
+    This means that you need to capture everything, i.e., include any library() calls and create all necessary objects.
+    The easiest way to make sure you've done this is to use the reprex package.
+
+-   Second, you need to make it minimal.
+    Strip away everything that is not directly related to your problem.
+    This usually involves creating a much smaller and simpler R object than the one you're facing in real life or even using built-in data.
+
+That sounds like a lot of work!
+And it can be, but it has a great payoff:
+
+-   80% of the time creating an excellent reprex reveals the source of your problem.
+    It's amazing how often the process of writing up a self-contained and minimal example allows you to answer your own question.
+
+-   The other 20% of time you will have captured the essence of your problem in a way that is easy for others to play with.
+    This substantially improves your chances of getting help!
+
+When creating a reprex by hand, it's easy to accidentally miss something that means your code can't be run on someone else's computer.
+Avoid this problem by using the reprex package which is installed as part of the tidyverse.
+Let's say you copy this code onto your clipboard (or, on RStudio Server or Cloud, select it):
+
+```{r, eval = FALSE}
+y <- 1:4
+mean(y)
+```
+
+Then call `reprex()`, where the default target venue is GitHub:
+
+``` r
+reprex::reprex()
+```
+
+A nicely rendered HTML preview will display in RStudio's Viewer (if you're in RStudio) or your default browser otherwise.
+The relevant bit of GitHub-flavored Markdown is ready to be pasted from your clipboard (on RStudio Server or Cloud, you will need to copy this yourself):
+
+    ``` r
+    y <- 1:4
+    mean(y)
+    #> [1] 2.5
+    ```
+
+Here's what that Markdown would look like rendered in a GitHub issue:
+
+```{r, eval = FALSE}
+y <- 1:4
+mean(y)
+#> [1] 2.5
+```
+
+Anyone else can copy, paste, and run this immediately.
+
+Instead of reading from the clipboard, you can:
+
+-   `reprex(mean(rnorm(10)))` to get code from expression.
+
+-   `reprex(input = "mean(rnorm(10))\n")` gets code from character vector (detected via length or terminating newline). Leading prompts are stripped from input source: `reprex(input = "> median(1:3)\n")` produces same output as `reprex(input = "median(1:3)\n")`
+
+-   `reprex(input = "my_reprex.R")` gets code from file
+
+-   Use one of the RStudio add-ins to use the selected text or current file.
 
 There are three things you need to include to make your example reproducible: required packages, data, and code.
 
@@ -42,11 +113,13 @@ There are three things you need to include to make your example reproducible: re
 
 Finish by checking that you have actually made a reproducible example by starting a fresh R session and copying and pasting your script in.
 
+## Investing in yourself
+
 You should also spend some time preparing yourself to solve problems before they occur.
 Investing a little time in learning R each day will pay off handsomely in the long run.
 One way is to follow what Hadley, Garrett, and everyone else at RStudio are doing on the [RStudio blog](https://blog.rstudio.org).
 This is where we post announcements about new packages, new IDE features, and in-person courses.
-You might also want to follow Hadley ([\@hadleywickham](https://twitter.com/hadleywickham)) or Garrett ([\@statgarrett](https://twitter.com/statgarrett)) on Twitter, or follow [\@rstudiotips](https://twitter.com/rstudiotips) to keep up with new features in the IDE.
+You might also want to follow Hadley ([\@hadleywickham](https://twitter.com/hadleywickham)), Mine ([\@minebocek](https://twitter.com/minebocek)), Garrett ([\@statgarrett](https://twitter.com/statgarrett)) on Twitter, or follow [\@rstudiotips](https://twitter.com/rstudiotips) to keep up with new features in the IDE.
 
 To keep up with the R community more broadly, we recommend reading <http://www.r-bloggers.com>: it aggregates over 500 blogs about R from around the world.
 If you're an active Twitter user, follow the ([`#rstats`](https://twitter.com/search?q=%23rstats)) hashtag.