diff --git a/README.md b/README.md
index 791075d979c..3755c5b9ccc 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ which for bonus points you can install with ansible!  Easy enough.
 Inventory file
 ==============
 
-To use ansible you must have a list of hosts somewhere.  The default inventory file (override with -H) is /etc/ansible/hosts and is a list of all hostnames to manage with ansible, one per line.  These can be hostnames or IPs.
+To use ansible you must have a list of hosts somewhere.  The default inventory host list (override with -l) is /etc/ansible/hosts and is a list of all hostnames to manage with ansible, one per line.  These can be hostnames or IPs.
 
 Example:
 
@@ -91,8 +91,8 @@ JSON files can be placed for template metadata using Jinja2.  Variables
 placed by 'setup' can be reused between ansible runs.
 
     ansible -p "*" -n setup -a "favcolor=red ntp_server=192.168.1.1"
-    ansible -p "*" -n template /srv/motd.j2 /etc/motd 
-    ansible -p "*" -n template /srv/ntp.j2 /etc/ntp.conf
+    ansible -p "*" -n template -a "src=/srv/motd.j2 dest=/etc/motd"
+    ansible -p "*" -n template -a "src=/srv/ntp.j2 dest=/etc/ntp.conf"
 
 Need something like the fqdn in a template?  If facter or ohai are installed, data from these projects
 will also be made available to the template engine, using 'facter_' and 'ohai_'
@@ -142,7 +142,7 @@ multple patterns in a single file.
       - name: configure template & module variables for future template calls
         action: setup http_port=80 max_clients=200
       - name: write the apache config file
-        action: template src=/srv/templates/httpd.j2 dest=/etc/httpd/conf
+        action: template src=/srv/templates/httpd.j2 dest=/etc/httpd.conf
         notify:
         - restart apache
       - name: ensure apache is running
@@ -155,7 +155,7 @@ See the playbook format manpage -- [ansible-playbook(5)](https://github.com/mpde
 
 To run a playbook:
 
-    ansible -r playbook.yml
+    ansible-playbook playbook.yml
 
 API
 ===
diff --git a/docs/man/man1/ansible.1.asciidoc b/docs/man/man1/ansible.1.asciidoc
index c4be91507b9..e805c1d1331 100644
--- a/docs/man/man1/ansible.1.asciidoc
+++ b/docs/man/man1/ansible.1.asciidoc
@@ -12,38 +12,44 @@ ansible - run a command somewhere else
 
 SYNOPSIS
 --------
-ansible [-H hosts_path] [-L library_path] [-f forks] [-n module_name]
-        [-a [args1 [args2 ...]]] [-p host_pattern] [-u remote_user]
+ansible [-f forks] [-p pattern ] [-u remote_user]
+        [-n module_name] [-a [args1 [args2 ...]]]
 
 
 DESCRIPTION
 -----------
 
-*Ansible* is an extra-simple Python API for doing \'remote things' over
+*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
 SSH.
 
 
 OPTIONS
 -------
 
-*-P*, *--askpass*::
+*-k*, *--ask-pass*::
 
-Ask the user to input the ssh password for connecting.
+Ask the user to input the ssh password for connecting.  Generally using
+ssh-agent instead is preferred.
 
 
-*-H*, *--host-list*::
+*-l*, *--host-list*::
 
-Path to hosts list.
+Path to hosts list, which defaults to /etc/ansible/hosts.  Users can use
+multiple files to emulate groups of systems.
 
 
-*-L*, *--library*::
+*-m*, *--module-path*::
 
-Path to module library.
+Override the path to module library, which defaults to /usr/share/ansible.
+The module library contains runnable modules that do 'things' to remote
+hosts.  See ansible-modules(5) for a list of those that bundled with
+Ansible.
 
 
 *-f*, *--forks*::
 
-Level of parallelism. Specify as an integer.
+Level of parallelism. Specify as an integer, the default is 3.  If set to "1" 
+debugging for certain classes of internal errors may become easier.
 
 
 *-n*, *--name*::
@@ -53,17 +59,15 @@ Module name to execute.
 
 *-a*, *--args*::
 
-Arguments to module.
+Arguments to module, as a single string.  Be sure to observe proper shell quoting rules.
+How these are handled are up to the module, but most modules take "key=value" pairs
+delimited by spaces.
 
 
 *-p*, *--pattern*::
 
-Hostname pattern. Accepts shell-like globs.
-
-
-*-r*, *--run-playbook*::
-
-Playbook file to run. Replaces the *-n* and *-a* options.
+Hostname pattern. Accepts shell-like globs which can be seperated with ";"
+The default is "*" which matches all hosts in the ansible hosts file.
 
 
 *-u*, *--remote-user*::
@@ -105,6 +109,8 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible-modules*(5), *ansible-playbook*(5)
+*ansible-modules*(5), 
+
+*ansible-playbook*(5),
 
 Ansible home page: <https://github.com/mpdehaan/ansible/>