diff --git a/examples/playbook.yml b/examples/playbook.yml
index f3c982a9823..be5a90d5749 100644
--- a/examples/playbook.yml
+++ b/examples/playbook.yml
@@ -1,28 +1,71 @@
 ---
+# this is an annotated example of some features available in playbooks
+# it shows how to make sure packages are updated, how to make sure
+# services are running, and how to template files.  It also demos
+# change handlers that can restart things (or trigger other actions)
+# when resources change.  For more advanced examples, see example2.yml
+
+# on all hosts, run as the user root...
+
 - hosts: all
   user: root
+
+  # make these variables available inside of templates
+  # for when we use the 'template' action/module later on...
+
   vars:
     http_port: 80
     max_clients: 200
-  vars_files:
-    - external_vars.yml
+
+  # define the tasks that are part of this play...
+
   tasks:
-  - name: simulate long running op (15 sec), wait for up to 45, poll every 5
+
+  # task #1 is to run an arbitrary command
+  # we'll simulate a long running task, wait for up to 45 seconds, poll every 5
+  # obviously this does nothing useful but you get the idea
+
+  - name: longrunner
     action: command /bin/sleep 15
     async: 45
     poll: 5
-  - name: fire and forget
-    action: command /bin/sleep 15
-    async: 45
-    poll: 0
-  - include: base.yml favcolor=blue
-  - name: write the foo config file using vars set above
+
+  # let's demo file operations.
+  #
+  # We can 'copy' files or 'template' them instead, using jinja2
+  # as the templating engine.  This is done using the variables 
+  # from the vars section above mixed in with variables bubbled up 
+  # automatically from tools like facter and ohai.  'copy' 
+  # works just like 'template' but does not do variable subsitution.
+  #
+  # If and only if the file changes, restart apache at the very
+  # end of the playbook run
+
+  - name: write some_random_foo configuration
     action: template src=foo.j2 dest=/etc/some_random_foo.conf
     notify:
     - restart apache
-  - name: ensure apache is running
+
+  # make sure httpd is installed at the latest version
+
+  - name: install httpd
+    action: yum pkg=httpd state=latest
+
+  # make sure httpd is running
+
+  - name: httpd start
     action: service name=httpd state=started
-  - name: pointless test action
-    action: command /bin/echo {{ http_port }}
+
+  # handlers are only run when things change, at the very end of each
+  # play.  Let's define some.  The names are significant and must
+  # match the 'notify' sections above
+
   handlers:
-    - include: handlers.yml
+
+    # this particular handler is run when some_random_foo.conf
+    # is changed, and only then
+
+    - name: restart apache
+      action: service httpd state=restarted
+
+