README.md in puppet-doc-lint-0.2.0 vs README.md in puppet-doc-lint-0.3.0

@@ -1,17 +1,52 @@
 # puppet-doc-lint
 [![Build Status](https://travis-ci.org/petems/puppet-doc-lint.png?branch=master)](https://travis-ci.org/petems/puppet-doc-lint)
 
 Lint your Puppet files for RDoc coverage
 
-This project is heavily based on the puppet-parse code base, go check it out! :smile:
+This project is heavily based on the [puppet-parse](https://github.com/johanek/puppet-parse) code base, go check it out! :smile:
 
+## Assumptions
+
+This assumes that you're formatting your documentation in Puppet with [RDoc formatting](http://rdoc.sourceforge.net/doc/).
+
+For example _this_ will work:
+
+```Rdoc
+# == Class: foo
+#
+# This module manages foo
+#
+# === Parameters
+#
+# [*ensure*]
+#   Controls presence of package and stuff
+#
+# === Authors
+#
+# * Jane Doe <mailto:[e-mail]>
+#
+```
+
+_This_ will not:
+
+```
+# Class: foo
+#
+# This module manages foo
+#
+# Parameters:
+# 	- $ensure
+#
+# Authors: Jane Doe <mailto:[e-mail]>
+#
+```
+
 ## Installation
 
     gem install puppet-doc-lint
 
-
 ## Usage
 
 ### By hand
 
 You can report on one or more manifests by running
@@ -25,9 +60,11 @@
 class firewall::linux::debian Parameters are ["ensure", "enable"]
 class firewall::linux::debian Docs found are ["ensure", "enable"]
 ```
 
 ### Rake task
+
+** Currrently broken maybe? **
 
 If you want to parse your entire modules directory, you can add
 `require 'puppet-doc-lint/rake-task' to your Rakefile and then run
 
     rake parse