Merge pull request #142 from getsentry/better-node-docs

Improve raven-node docs ...

Author: benvinegar

docs/index.rst

@@ -27,28 +27,30 @@ Raven is distributed via ``npm``:
 Configuring the Client
 ----------------------
 
-Now need to configure your application:
+Next you need to initialize the Raven client and configure it to use your `Sentry DSN
+<https://docs.getsentry.com/hosted/quickstart/#configure-the-dsn>`_:
 
 .. code-block:: javascript
 
+    var raven = require('raven');
     var client = new raven.Client('___DSN___');
 
-At this point you'll likely need to integrate it into your application via
-middleware or another integration mechanism. Take a look at our documentation
-on :doc:`integrations/index` and :doc:`usage`.
+You can optionally pass an object of configuration options as the 2nd argument to `Client`. For
+more information, see :doc:`config`.
 
 Reporting Errors
 ----------------
 
-You'll want to start by injecting a global error handler, which will catch any
-exceptions which would bubble up to the Node runtime:
+To get started passing errors to Raven, it is recommended to initialize Raven's global error handler using
+``patchGlobal``. This will cause any uncaught exception which would bubble up to the Node runtime to be
+captured and processed by Raven.
 
 .. code-block:: javascript
 
   client.patchGlobal();
 
-Beyond that, the simplest way is to explicitly capture and report potentially
-problematic code with a ``try...catch`` block and ``Raven.captureException``:
+Additionally, you can manually capture and report potentially problematic code with ``try...catch`` and
+ ``captureException``:
 
 .. code-block:: javascript
 
@@ -58,6 +60,8 @@ problematic code with a ``try...catch`` block and ``Raven.captureException``:
         client.captureException(e)
     }
 
+The ``captureException`` method optionally takes an object of configuration options as the 2nd argument. For more information, and to learn about other methods provided by the Raven API, see :docs:`usage`.
+
 Adding Context
 --------------
 

docs/install.rst

@@ -1,12 +1,16 @@
 Usage
 =====
 
-.. code-block:: javascript
+Capturing Errors
+----------------
 
-    var raven = require('raven');
-    var client = new raven.Client('___DSN___');
+.. code-block:: javascript
 
-    client.captureMessage('Hello, world!');
+    try {
+        doSomething(a[0])
+    } catch (err) {
+        client.captureException(err)
+    }
 
 Capturing Messages
 ------------------
@@ -15,15 +19,6 @@ Capturing Messages
 
     client.captureMessage('Broken!')
 
-Configuring the HTTP Transport
-------------------------------
-
-.. code-block:: javascript
-
-    var client = new raven.Client('___DSN___', {
-        transport: new raven.transports.HTTPSTransport({rejectUnauthorized: false})
-    });
-
 .. _raven-node-additional-context:
 
 Optional Attributes
@@ -165,6 +160,13 @@ so an optional callback is provided to allow you to hook in something like:
 
 The callback is called **after** the event has been sent to the Sentry server.
 
+
+Middleware and Integrations
+---------------------------
+
+If you're using Node.js with a web server framework/library like Connect, Express, or Koa, it is recommended
+to configure one of Raven's server middleware integrations. See doc:`integrations/index`.
+
 Events
 ------
 
@@ -187,6 +189,14 @@ If you really care if the event was logged or errored out, Client emits two even
 
     client.captureMessage('Boom');
 
+Configuring the HTTP Transport
+------------------------------
+
+.. code-block:: javascript
+
+    var client = new raven.Client('___DSN___', {
+        transport: new raven.transports.HTTPSTransport({rejectUnauthorized: false})
+    });
 
 Disable Raven
 -------------