README.Rmd

---
title: "Help Please! Starting out in R - with a little help from your friends"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Help Please!}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# About `helpPlease`

** Still in proof of concept **

Starting out in R can be quite overwhelming. There are lots of resources and people around who want to help, but navigating those can be hard and some of the R error messages and explainers within R itself can seem like something of a foreign language.

helpPlease is there to bridge the gap. The gap closes by itself over time, but let's build a bridge and make life easier.

# Who is `helpPlease` for?

`helpPlease` is aimed at new users of R. It aims to introduce them to the language we use to explain things in R, helpful websites and tutorials that provide help _and_ the R stats community that builds them - all from the console. 

As a new user, the depth and breadth of the R ecosystem can be hard to navigate. `helpPlease` provides help as well as an in-console tour of that ecosystem.

## I'm new to R, how do I use `helpPlease`?

Be warned, `helpPlease` is in proof of concept phase. It's not very helpful right now. However, if you want to have a go at testing it (and we'd love that!), here's the code you should paste into the command line of your computer:

```{r, eval = FALSE, echo = TRUE}
require(devtools) # You only need this line one time
install_github("stephdesilva/helpPlease") # You only need this line one time
```

Use the command `library(helpPlease)` every time you'd like to use the package, but the other two lines you only need to run once to get the package onto your local computer.

```{r, eval = FALSE, echo = TRUE}
library(helpPlease) # You will need this line every time you want to use the 
                    # package in a new session of R.
```


# What's in `helpPlease` right now?

There are currently four main functions in this tester phase of the helpPlease. These are `helpError()`, `defineMe()`, `encourager()` and `troubleShooter()`.

## `helpError()` 

This function takes a key phrase from the error you don't understand and looks for a plain language explanation from our database. It may also be able to provide you with helpful links or tips.

For example, say you are presented with the error: `Error in library(abcd) : there is no package called ‘abcd’`

    ```
    helpError("there is no package called")
    ```

## `defineMe()`

Did you ever wonder what _atomic_ refers to in R? What's a _closure_ and why is it not _subsettable_? This function takes the word you're unsure about and searches for a plain language explanation from our database. There may be links to further reading!

For example, say you are presented with the error `Error in encourager[4, 5] : object of type 'closure' is not subsettable` and you'd like to know what on earth a closure is.

    ```
    defineMe("closure")
    ```

## `encourager()` 

We all need to know we're not the only person who ever spent four hours looking for a missing comma. Inspired by the `praise` package, which teaches new programmers to write packages, the `encourager()` function will give you the insights and favourite resources of your R stats community straight to the console.

For example, you're ready to throw your laptop out the window. Please don't, you'll regret it when you're trying to type great tweets on your phone tonight. Instead, try: 

    ```
        encourager()
    ```

## `troubleShooter()`

New to programming and finding all the stuff you _don't know_ really matters? `troubleShooter()` will put tips and tricks from the R stats community right into your console. You don't know what you don't know - until someone takes the time to tell you.
    + For example, you've spent the last hour looking for a missing comma (it happens), try: 
    
    ```
        troubleShooter()
    ```
  
## Future functions

There are a couple of functions we'd like to add to `helpPlease` in the future:
    
`addDefinition()`: this function will allow you to add your own definitions to your own local database for future reference. Notice something interesting or difficult? Make a note for yourself so you can retrieve it later.
    
`addError()`: there's nothing worse than spending ages finding out the solution to your error... and then forgetting it a week later. This function will allow you to add your own specific errors, fixes, notes and useful links to your own local database for future reference.
    
# How big is `helpPlease`'s database?

Pretty miniscule right now. The current version is a proof of concept database and package. Before it goes to CRAN we will need to build it to a useable size.

You can help! If you have a weird error message that could use explaining in plain text, a word that would be helpful to define for new users, some encouragement or a troubleshooting tip, [please use the form here](https://goo.gl/forms/KzRGbmqmGmM6P9Nn1).

# What next?

This package is in proof of concept phase. We're tinkering with it to make sure everything works easily, build vignettes to make it easy for new users to navigate and to generate a database that's big enough to be helpful.

If you'd like to contribute, we'd love to hear from you.