Expand and rewrite the README file.

Author: robmiller

README.md

@@ -1,13 +1,22 @@
-# jQuery Client Side Logging Plugin
+# jQuery.clientSideLogging, the jQuery client side logging plugin
 
 ## About
 
-The idea behind this plugin was born from [reading this article](http://openmymind.net/2012/4/4/You-Really-Should-Log-Client-Side-Error/).
-The plugin has the ability to include some useful stats like the user agent, window size, and hopefully more in the future.
+We've all been there; someone's encountering an error on your site, but everything's fine for you. What browser are they using? What's the error message? How many people is this affecting? Usually, you're in the dark: but no more!
+
+With clientSideLogging, you can quietly log the errors that your users encounter (and also some debugging info of your own, if you like) and collate it server-side. Then, when you hear of a problem, you can check the logs — and see whether it's affecting one person or one thousand, one browser or many. You can even log useful information like screen resolution and browser size, for those inevitable small- or big-screen edge-cases.
+
+The inspiration for this jQuery plugin came from [Karl Seguin's excellent article](http://openmymind.net/2012/4/4/You-Really-Should-Log-Client-Side-Error/).
 
 ## Usage
 
-The first thing that needs be done is you need to specify the urls the messages will be sent to (the ones in the example below are the default ones):
+### Frontend
+
+First things first, you need to set up your JavaScript code to log errors. Setup is easy; just include the jQuery plugin after jQuery, and call:
+
+	$.clientSideLogging();
+
+There are some default arguments that you can override. At the very least, you should set the `error_url`, `info_url`, and `log_url` settings to point to your backend:
 
 	$.clientSideLogging({
 		error_url: '/log?type=error',	// The url to which errors logs are sent
@@ -25,17 +34,24 @@ The first thing that needs be done is you need to specify the urls the messages
 		}
 	});
 
-*Important to note* at this point is that you need to have something set up on the server side to receive the errors and handle them accordingly.
-Thanks to [Rob Miller](https://github.com/robmiller) for the example logging functionality and for contributing in general. You can find this in the [test directory](https://github.com/remybach/jQuery.clientSideLogging/tree/master/test)
-
-Once you've specified the urls (or are happy with the defaults), you have three utility/wrapper functions available to you (all of which receive either a string or a json formatted object):
+Now, to actually use it! By default, clientSideLogging hooks into `window.error`, to catch all JavaScript errors; however, you can also log values yourself, using three utility/wrapper functions. All of them accept either a plain string or a JavaScript object:
 
-* `$.error(what)` - Send an error message to the server, also does a console.error (if available)
-* `$.info(what)` - Send an info message to the server, also does a console.info (if available)
-* `$.log(what)` - Send a log message to the server, also does a console.log (if available)
+* `$.error(what)` - Send an error message to the server; also calls console.error (if available)
+* `$.info(what)` - Send an info message to the server; also calls console.info (if available)
+* `$.log(what)` - Send a log message to the server; also calls console.log (if available)
 
-If a string is received, the info will be sent to the backend as a normal post request which might look similar to the following:
+The log will be sent to the backend as a normal `POST` request, which might look like the following:
 
 	$.post('/log?type=error&msg=YOUR_ERROR_MESSAGE');
 
-Otherwise if a JSON object is received, the info will be sent as an encoded JSON string that can be decoded on the backend.
+### Backend
+
+Sending errors is all well and good, but not if you've not got anything to receive them! So, you need to have something on your server that will store error messages sent to it.
+
+Included in the distribution is a sample backend that should suffice for most people; it stores logs in a JSON-serialised text file, so it should be portable and relatively fast.
+
+This default backend will write its logs to a file called `log.txt` in its current directory; simply edit the `LOG_FILE` constant to change this — something that's highly recommended, to keep things private.
+
+### Viewing the logs
+
+Also included with the distribution is a PHP frontend for parsing and displaying log entries; called `view_logs.php`, this script looks for the log file generated by the `log.php` script (make sure the `LOG_FILE` constant in the two of them matches) and displays a few nicely formatted tables of log information, and allows you to filter by severity.