docs(:book:): new conceptual guide to introduce the lib

ISSUES CLOSED: #318

README.md

@@ -76,10 +76,10 @@ Some useful commands include:
 * [`@esri/arcgis-rest-groups`](./packages/arcgis-rest-groups) - Methods for working with ArcGIS Online/Enterprise groups.
 * [`@esri/arcgis-rest-users`](./packages/arcgis-rest-users) - Methods for working with ArcGIS Online/Enterprise users.
 * [`@esri/arcgis-rest-sharing`](./packages/arcgis-rest-sharing) - Methods for updating permissions for ArcGIS Online/Enterprise content.
-* [`@esri/arcgis-rest-feature-service`](./packages/arcgis-rest-feature-service) - Functions for working with feature services
+* [`@esri/arcgis-rest-feature-service`](./packages/arcgis-rest-feature-service) - Functions for querying and editing the features inside feature services.
 * [`@esri/arcgis-rest-geocoder`](./packages/arcgis-rest-geocoder) - Geocoding wrapper for `@esri/arcgis-rest-js`
-* [`@esri/arcgis-rest-feature-service-admin`](./packages/arcgis-rest-feature-service-admin) - Functions for creating and updating feature services
-* [`@esri/arcgis-rest-routing`](./packages/arcgis-rest-routing) - Stores objects common across the ArcGIS API.
+* [`@esri/arcgis-rest-feature-service-admin`](./packages/arcgis-rest-feature-service-admin) - Functions for creating and updating feature services.
+* [`@esri/arcgis-rest-routing`](./packages/arcgis-rest-routing) - Routing and directions wrapper for `@esri/arcgis-rest-js`.
 * [`@esri/arcgis-rest-common`](./packages/arcgis-rest-common) - Stores shared methods and types used throughout the ArcGIS API.
 
 

docs/src/guides/node.md

@@ -63,7 +63,7 @@ const authentication = new UserSession({
   password: "123456"
 })
 ```
-See the [Browser Authenication](../browser-authentication/) for more information about implementing OAuth 2.0.
+See the [Browser Authentication](../browser-authentication/) for more information about implementing OAuth 2.0.
 
 
 

docs/src/guides/package-overview.md

@@ -5,4 +5,107 @@ order: 10
 group: 0-introduction
 ---
 
+# Why `@esri/arcgis-rest`?
+
+`@esri/arcgis-rest` simplifies interacting with ArcGIS Online and Enterprise in both browsers and Node.js.
+
+There's no better way to explain what that means than comparing an `@esri/arcgis-rest` call to the same web request made using plain old JavaScript.
+
+```js
+import { getUser } from "@esri/arcgis-rest-users";
+
+// pass in a username and get back information about the user
+getUser(`jgravois`)
+  .then(response) // { firstName: "john", description: "open source geodev" ... }
+```
+
+```js
+// construct the url yourself and don't forget to tack on f=json
+const url = "https://www.arcgis.com/sharing/rest/community/users/jgravois?f=json";
+
+var xhr = new XMLHttpRequest();
+xhr.onreadystatechange = function() {
+  if (xhr.readyState == XMLHttpRequest.DONE) {
+    xhr.responseText; // { firstName: "john", description: "open source geodev" ... }
+  }
+}
+xhr.open('GET', url, true);
+xhr.send(null);
+```
+
+wow, thats a lot easier! `@esri/arcgis-rest` is able to intuit the actual url (by default it assumes you're interacting with ArcGIS Online) prior to making the request and internalizes a lot of tedious logic for handling the response.
+
+Our packages tap into a new JavaScript spec called [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) under the hood though, so lets compare 🍎s to 🍎s.
+
+```js
+import { deleteFeatures } from "@esri/arcgis/rest-feature-service";
+
+const url = `http://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/1/`
+
+// https://esri.github.io/arcgis-rest-js/api/feature-service/deleteFeatures/
+deleteFeatures({
+  url,
+  objectIds: [ 2360245 ]
+})
+  .then(response)
+```
+
+```js
+// append operation name to url
+url += `deleteFeatures`;
+
+fetch(url, {
+  // set the request type
+  method: "POST",
+  // append appropriate headers
+  headers: {
+    "Content-Type": "application/x-www-form-urlencoded"
+  },
+  // concatentate and encode each parameter manually
+  // and remember to append f=json
+  body: `objectIds=${encodeURIComponent(2360245)}&f=json`
+})
+  .then(response => {
+    // cast the response as JSON
+    if (response.ok) {
+      return response.json()
+    }
+  })
+  .then(response => {
+    // trap for ArcGIS error objects in 200 responses
+    if (!response.error) {
+      console.log(response);
+    }
+  })
+```
+
+As you can see, `@esri/arcgis-rest` is still handling a _lot_ of the details internally.
+
+* the operation name is appended to urls
+* a `"POST"` is made automatically (when appropriate)
+* query string parameters are encoded
+* appropriate `headers` are appended
+* `FormData` is created internally (when necessary)
+* `200` responses that contain an error are trapped for
+* the generic `f=json` parameter is appended
+
+And we haven't even begun to discuss [authentication](../node/).
+
+Whether you're trying to automate interacting with premium services in Node.js or creating a website that will allow users to sign into [ArcGIS Online](https://www.arcgis.com) safely and manage their own content, `@esri/arcgis-rest` has you covered.
+
 # Package Overview
+
+The library is a collection of _very_ small mix and match packages that are framework agnostic and make a variety of ArcGIS tasks more convenient.
+
+* [`@esri/arcgis-rest-request`](../../api/request/) - Underpins other packages and supports making generic web requests.
+* [`@esri/arcgis-rest-auth`](../../api/auth) - Provides methods for authenticating named users and applications.
+* [`@esri/arcgis-rest-common-types`](../../api/common-types) - TypeScript types that are common across the ArcGIS API.
+* [`@esri/arcgis-rest-items`](../../api/items) - Methods for working with ArcGIS Online/Enterprise content.
+* [`@esri/arcgis-rest-groups`](../../api/groups) - Methods for working with ArcGIS Online/Enterprise groups.
+* [`@esri/arcgis-rest-users`](../../api/users) - Methods for working with ArcGIS Online/Enterprise users.
+* [`@esri/arcgis-rest-sharing`](../../api/sharing) - Methods for updating the permissions of ArcGIS Online/Enterprise content.
+* [`@esri/arcgis-rest-feature-service`](../../api/feature-service) - Functions for querying and editing the features inside feature services
+* [`@esri/arcgis-rest-geocoder`](../../api/geocoder) - Geocoding wrapper for `@esri/arcgis-rest-js`.
+* [`@esri/arcgis-rest-feature-service-admin`](../../api/feature-service-admin) - Functions for creating and updating feature services
+* [`@esri/arcgis-rest-routing`](../../api/routing) - Routing and directions wrapper for `@esri/arcgis-rest-js`.
+* [`@esri/arcgis-rest-common`](../../api/common) - Stores shared methods and types used throughout the ArcGIS API.