Better docs

README.md

@@ -1,16 +1,54 @@
 ## Janitor
 
-It keeps the things running at the right intervals. But different than cron.
+Janitor is a program somewhat similar to cron.  Unlike cron, Janitor
+cannot run programs at specific times, only at intervals (eg, every 5
+minutes, or every 2 seconds).
 
-Janitor is built on NodeJS.
+Janitor has a unique spin, however: It can also run programs *after*
+another program has completed. This is quite useful in scenarios where you
+have a number of programs that need to be run at regular intervals and in
+a specific order.
 
-With Janitor, you can schedule commands to run at specific intervals (eg,
-every 30 seconds). You can also schedule commands to run after other
-commands have completed.
+In addition to relative scheduling, Janitor also provides basic watchdog
+capabilities. When Janitor starts up, it will start all watched processes,
+and if one dies, it will attempt to restart it and notify you.
 
-At Bet Smart, we use the Janitor to run a number of post-processing
-tasks after a data feed has been consumed.
 
-Janitor also provides basic watchdog capabilities.  If a process dies,
-Janitor will restart it and notify the admin.
+### Example: Scheduling
+
+Say you have a script that fetches an external XML data feed, processes
+it, and loads it into your local database.  Once the ETL process is
+complete, you want to perform some post-processing actions on it.
+
+This is an ideal use case for Janitor.  You can accomplish this with the
+following configuration excerpt:
+
+```
+{
+	"schedule": {
+		"etl":       {"cmd":"etl.js", "when":"every 60s"},
+		"postproc1": {"cmd":"pp1.js", "when":"after postproc1"},
+		"postproc2": {"cmd":"pp2.js", "when":"after postproc1"}
+	}
+}
+```
+
+### Example: Watchdog
+
+This excerpt will log all output from the watch_me.sh script to a file. If
+the script dies, it will restart it and notify the administrator.
+
+```
+{
+	"admin": "admin@example.com",
+
+	"daemon": true,
+	"log": "janitor.log",
+	"pid": "janitor.pid",
+
+	"watch": {
+		"watch1": {"cmd":"watch_me.sh", "notify":true, "output":"watch1.log"}
+	}
+}
+```
 

janitor.js

@@ -15,7 +15,6 @@
  * This code works on NodeJS 0.4.12.
  *
  * TODO: use nodules for hot-loading config?
- * TODO: docs
  */
 
 var sys        = require("sys");