The example for the fail module doesn't work:
  http://www.ansibleworks.com/docs/modules.html#fail

The current text shows:
    - fail: msg="The system may not be provisioned according to the CMDB status."
      when: "{{ cmdb_status }} != 'to-be-staged'"

The "when" documentation indicates that the argument is already a Jinja2
expression:
  http://www.ansibleworks.com/docs/playbooks_conditionals.html#the-when-statement

Thus, the following is
      when: cmdb_status != "to-be-staged"

is preferred even though the following could work but generates a
deprecation warning:
      when: {{cmdb_status != "to-be-staged"}}

Use when instead of only_if
Use new variable style

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

This makes more sense as there is no purpose in running these remotely.

 - added terse syntax to modules.rst
 - added description of special variables to template module

Fix indent of fail module example to prevent unwanted `<blockquote></pre></p> <br/></blockquote>` from showing up in docsite output.

In some cases you may want to deliberately fail the execution of a playbook. In our provisioning workflow we want to have safeguards in place to avoid provisioning systems that are already in production. Since we reboot physical and virtual systems, it is mandatory we take all the precautions to prevent accidental provisioning.

So in our use-case we have the following at the very start of the provisioning playbook:

    ### Safeguard to protect production systems
    - local_action: fail msg="System is not ready to be staged according to CMDB"
      only_if: "'$cmdb_status' != 'to-be-staged'"

and we repeat the same task in the (separate included) play that takes care of (re)booting the system using our own boot-media, so that it cannot be accidentally separately run by someone.