improved docs

readme.md

@@ -10,6 +10,70 @@
 
 ## Usage
 
+### Create a new feed
+
+```js
+var RSS = require('rss');
+
+var feed = new RSS(feedOptions);
+```
+
+#### `feedOptions`
+
+ * `title` **string** Title of your site or feed
+ * `description` _optional_ **string** A short description of the feed.
+ * `generator` _optional_  **string** Feed generator.
+ * `feed_url` **url string** Url to the rss feed.
+ * `site_url` **url string** Url to the site that the feed is for.
+ * `image_url` _optional_  **url string* Small image for feed readers to use.
+ * `docs` _optional_ **url string** Url to documentation on this feed.
+ * `author` **string** Who owns this feed.
+ * `managingEditor` _optional_ **string** Who manages content in this feed.
+ * `webMaster` _optional_ **string** Who manages feed availability and technical support.
+ * `copyright` _optional_ **string** Copyright information for this feed.
+ * `language` _optional_ **string**  The language of the content of this feed.
+ * `categories` _optional_ **array of strings**  One or more categories this feed belongs to.
+ * `pubDate` _optional_ **Date object or date string** The publication date for content in the feed
+ * `ttl` _optional_ **integer** Number of minutes feed can be cached before refreshing from source.
+
+### Add items to a feed
+
+An item can be used for a blog entry, project update, log entry, etc.  Your RSS feed
+an have any number of items. Most feeds use 20 or fewer items.
+
+```js
+feed.item(itemOptions);
+```
+
+#### itemOptions
+
+ * `title` **string** Title of this particular item.
+ * `description` **string** Content for the item.  Can contain html but link and image urls must be absolute path including hostname.
+ * `url` **url string** 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.
+ * `categories` _optional_ **array of strings** If provided, each array item will be added as a category element
+ * `author` _optional_  **string**  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 item was created.  Feed
+ readers use this to determine the sort order. Some readers will also use it to determine
+ if the content should be presented as unread.
+
+#### Feed XML
+
+```js
+var xml = feed.xml(indent);
+```
+
+This returns the XML as a string.
+
+`indent` _optional_ **string** What to use as a tab. Defaults to no tabs (compressed).
+ For example you can use `'\t'` for tab character, or `'  '` for two-space tabs.
+
+## Example Usage
+
 ```js
 var RSS = require('rss');
 
@@ -43,60 +107,10 @@ feed.item({
     enclosure : {url:'...', file:'path-to-file'} // optional
 });
 
-// cache the xml
+// cache the xml to send to clients
 var xml = feed.xml();
 ```
 
-### Feed Options
-
- * `title` **string** Title of your site or feed
- * `description` _optional_ **string** A short description of the feed.
- * `generator` _optional_  **string** Feed generator.
- * `feed_url` **url string** Url to the rss feed.
- * `site_url` **url string** Url to the site that the feed is for.
- * `image_url` _optional_  **url string* Small image for feed readers to use.
- * `docs` _optional_ **url string** Url to documentation on this feed.
- * `author` **string** Who owns this feed.
- * `managingEditor` _optional_ **string** Who manages content in this feed.
- * `webMaster` _optional_ **string** Who manages feed availability and technical support.
- * `copyright` _optional_ **string** Copyright information for this feed.
- * `language` _optional_ **string**  The language of the content of this feed.
- * `categories` _optional_ **array of strings**  One or more categories this feed belongs to.
- * `pubDate` _optional_ **Date object or date string** The publication date for content in the feed
- * `ttl` _optional_ **integer** Number of minutes feed can be cached before refreshing from source.
-
-### 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 twenty 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 be absolute path including hostname.
- * `url` **url string** 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.
- * `categories` _optional_ **array of strings** If provided, each array item will be added as a category element
- * `author` _optional_  **string**  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 item was created.  Feed
- readers use this to determine the sort order. Some readers will also use it to determine
- if the content should be presented as unread.
-
-### Methods
-
-#### `item(item_options)`
-
-Add an rss item/article.
-
-#### `xml([indent])`
-
-Return the xml.
-
-If you pass in `true` it will use four spaces for indenting. If you prefer
- tabs pass in `\t` instead of true, or a two space string for two space tabs.
-
 ## Tests
 
 Tests included use Mocha. Use `npm test` to run the tests.
@@ -108,13 +122,17 @@ Tests included use Mocha. Use `npm test` to run the tests.
  * This module is very fast but you might as well cache the output of xml() and serve
  it until something changes.
 
+# History
+
+I started this module over two years ago (April 2011) because there weren't any Node modules
+for creating RSS. Besides these [25 modules](https://npmjs.org/browse/depended/rss)
+I would love to know what other projects are using it.
+
 # Contributing
 
 Contributions to the project are welcome. Feel free to fork and improve.
-I accept pull requests when tests and updated docs are included.
+I do my best accept pull requests in a timely manor, especially when tests and updated docs
-
+are included.
-I'm not actively adding features to this module. If you would like to take over maintaining it
-just let me know.
 
 # License