another pass at the readme

readme.md

@@ -4,7 +4,7 @@
 
 ## Install
 
-   $ npm install rss
+    $ npm install rss
 
 ## Tests
 
@@ -17,23 +17,8 @@
 
     var RSS = require('rss');
 
-    // new feed
-    var feed = new RSS(feed_options);
-
-    // add your items/entries/articles.
-    feed.item(item_options)
-       .item(item_options);
-
-    // cache the result
-    var xml = feed.xml();
-
-
-### feed_options
-
-        var RSS = require('rss');
-
-        // new feed
-        var rss = new RSS({
+    /* lets create an rss feed */
+    var feed = new RSS({
             title: 'title',
             description: 'description',
             feed_url: 'http://example.com/rss.xml',
@@ -42,10 +27,8 @@
             author: 'Dylan Greene'
         });
 
-
-### item_options
-
-    rss.item({
+    /* loop over data and add to feed */
+    feed.item({
         title:  'item title',
         description: 'use this for the content. It can include html.',
         url: 'http://example.com/article4?this&that', // link to the item
@@ -54,6 +37,36 @@
         date: 'May 27, 2012' // any format that js Date can parse.
     });
 
+    // cache the xml
+    var xml = feed.xml();
+
+### Feed Options
+
+ * _title_ <string> Title of your site or feed
+ * _description_ <string> Optional. Short description of the feed.
+ * _feed_url_ <url> Url to the rss feed.
+ * _site_url_ <url> Url to the site that the feed is for.
+ * _image_url_ <url> Optional. Small image for feed readers to use.
+ * _author_ <string> Who owns this feed.
+
+### Item Options
+
+In RSS an item can be used for a blog entry, project update, log entry, etc.  Your rss feed
+an have any number of items. Ten to tenty is usually good.
+
+ * _title_ <string> Title of this particular item.
+ * _description_ <string> Content for the item.  Can contain html but link and image urls must include the server name.
+ (Note: I might change this to content in the next release.)
+ * _url_ <url> Url to the item. This could be a blog entry.
+ * _guid_ <unique string> A unique string feed readers use to know if an item is new or has already been seen.
+ If you use a guid never change it.  If you don't provide a guid then your item urls must
+ be unique.
+ * _author_ <string> Optional.  If included it is the name of the item's creator.
+ If not provided the item author will be the same as the feed author.  This is typical
+ except on multi-author blogs.
+ * _date_ <Date object or date string> The date and time of when the intem was created.  Feed
+ readers use this to determin the sort order. Some readers will also use it to determin
+ if the content should be presented as unread.
 
 ### Methods
 
@@ -63,12 +76,17 @@
 
 ## Notes
  * You do not need to escape anything. This module will escape characters when necessary.
+ * This module is very fast but you might as well cache the output of xml() and serve
+ it until something changes.
 
 ## Upcoming features
 
  * Atom support
  * Feed validation
+ * Feedburner integration
  * More customization
+ * Express middleware for serving feeds
+ * What else?
 
 # Contributing