Update readme

Author: rstacruz

README.md

@@ -1,11 +1,12 @@
 # docpress-core
 
-How it works:
+Metalsmith plugin to generate Docpress site data from a project. Part of the [Docpress] project.
 
-1. make a toc in `docs/README.md`
-2. renders a site based on it
+This plugin generates bare HTML files (just rendered from Markdown) from a project. It also creates a `toc.json` (Table of contents) and `index.json` (Page index). This is usually used with [docpress-base], which will then prettify those pages into a full-fleged website.
 
-sample:
+## How it works
+
+Make a TOC in `docs/README.md`. This will be used to crawl the project for files to be parsed. Here's an example structure:
 
 ```
 README.md
@@ -18,5 +19,18 @@ docs/
 
 ## API
 
-* `docpress-core` - Metalsmith middleware.
-* `docpress-core/ms` - Metalsmith instance generator.
+You get these modules:
+
+- `docpress-core` The main Metalsmith middleware.
+- `docpress-core/ms` - Metalsmith instance generator.
+
+You use them together like so:
+
+```js
+var app = require('docpress-core/ms')(cwd)
+  .use(require('docpress-core')())
+  .use(require('docpress-base')())
+```
+
+[Docpress]: https://github.com/docpress/docpress
+[docpress-base]: https://github.com/docpress/docpress-base