Merge pull request #4 from rstudio/sean-docs

update readme to be more userfacing

README.md

@@ -1,6 +1,94 @@
 # r-builds
 
-The environment which produces R builds obtainable from: https://cdn.rstudio.com/r/versions.json
+This repository orchestrates tools to produce R binaries obtainable from:
+https://cdn.rstudio.com/r. The binaries are available as a
+community resource, **they are not professionally supported by RStudio**. 
+The R language is open source, please see the official documentation at https://www.r-project.org/.
+
+These binaries are not a replacement to existing binary distributions for R.
+The binaries were built with the following considerations:
+- They use a minimal, documented set of
+  [build](https://github.com/rstudio/r-builds/tree/master/builder) and
+  [runtime](https://github.com/rstudio/r-docker) dependencies.  
+- They are designed to be used side-by-side, e.g., on [RStudio Server Pro](https://docs.rstudio.com/ide/server-pro/r-versions.html#using-multiple-versions-of-r-concurrently).
+- They give users a consistent option for accessing R across different Linux distributions.
+
+These binaries have been extensively tested, and are used in production everyday
+on [RStudio Cloud](https://rstudio.cloud) and
+[shinyapps.io](https://shinyapps.io). Please open an issue to report a specific
+bug, and address questions on [RStudio
+Community](https://community.rstudio.com).
+
+## Example Usage
+
+These binaries are designed to be copied onto a server, as opposed to installed
+using a system package manager like `apt` or `yum`. This approach allows administrators
+to offer multiple versions of R side-by-side. 
+
+```bash
+# Install runtime pre-reqs
+# Then copy the desired R version from the CDN
+
+OS_IDENTIFIER=ubuntu-1804
+R_VERSION=3.5.3
+
+wget -O R-${R_VERSION}.tar.gz https://cdn.rstudio.com/r/${OS_IDENTIFIER}/R-${R_VERSION}-${OS_IDENTIFIER}.tar.gz 
+mkdir -p /opt/R 
+tar zx -C /opt/R -f ./R-${R_VERSION}.tar.gz 
+rm R-${R_VERSION}.tar.gz
+
+# execute R from this directory
+/opt/R/${R_VERSION}/bin/R -e 'capabilities()'
+
+# optionally add this version to the path
+PATH=/opt/R/${R_VERSION}/bin:${PATH}
+
+# OR optionally link the binaries to /usr
+ln -s /opt/R/${R_VERSION}/bin/R /usr/bin/R 
+ln -s /opt/R/${R_VERSION}/bin/Rscript /usr/bin/Rscript
+ln -s /opt/R/${R_VERSION}/lib/R /usr/lib/R 
+```
+The R binary can be obtain from the CDN using a URL with the format:  
+
+```
+https://cdn.rstudio.com/r/<OS_IDENTIFIER>/R-<R_VERSION>-<OS_IDENTIFIER>.tar.gz
+```
+
+The list of currently available R versions can be obtained here:
+https://cdn.rstudio.com/r/versions.json.  
+
+The following operating systems are supported:  
+
+|Operating System|OS Identifier| 
+|---|---|
+|CentOS 6|centos-6|
+|CentOS 7|centos-7|
+|Debian 9|debian-9|
+|OpenSUSE 15.1|opensuse-15|
+|OpenSUSE 42.3|opensuse-42|
+|Ubuntu 16.04 Xenial|ubuntu-1604|
+|Ubuntu 18.04 Bionic|ubuntu-1804|
+
+The R binaries are built on these open source containers, but have been tested
+on their commerical equivalents. For example, the CentOS binaries also work on
+RedHat Enterprise Linux (REHL) and the OpenSUSE binaries also worn on SUSE Linux
+Enterprise Server (SLES).
+
+Please see [r-docker](https://github.com/rstudio/r-docker) and
+[r-system-requirements](https://github.com/rstudio/r-system-requirements) for
+more information on using these binaries. The `r-docker` repository documents
+required runtime system dependencies and provides users with docker images
+containing these dependencies. The `r-system-requirements` repository contains
+information on the additional system dependencies that may be required to
+install and use R packages.
+
+---
+
+# Developer Documentation
+
+This repository orchestrates builds using a variety of tools built. The
+instructions below outline the components in the stack and describe how to add a
+new platform or inspect an existing platform.
 
 ## Adding a new platform.