Issue #84: Doc tweaks for modules, moduledev, and playbooks

rst/moduledev.rst

@@ -188,11 +188,13 @@ You should also never do this in a module::
 Because the output is supposed to be valid JSON.  Except that's not quite true,
 but we'll get to that later.
 
-Further, modules must not output anything on stderr, even if the JSON returned
-out stdout is valid.  This is due to the internals of our SSH library, more or less.
+Modules must not output anything on standard error, because the system will merge
+standard out with standard error and prevent the JSON from parsing. Capturing standard
+error and returning it as a variable in the JSON on standard out is fine, and is, in fact,
+how the command module is implemented.
 
 If a module returns stderr or otherwise fails to produce valid JSON, the actual output
-will still be shown in Ansible, however, but the command will not succeed.
+will still be shown in Ansible, but the command will not succeed.
 
 Always use the hacking/test-module script when developing modules and it will warn
 you about these kind of things.

rst/modules.rst

@@ -431,7 +431,9 @@ on your remote systems.
 
 *variablename*:
 
- * Arbitrary names can be used as variables. 'variablename' can be basically anything, and sets a ``key=value`` pair in the JSON file for use in templating.
+* Arbitrary variable names, which must be a mix of alphanumeric characters and
+underscores, can also be defined. Setting a variable creates a
+``key=value`` pair in the JSON file for use in templating.
 
 Example action from Ansible :doc:`playbooks`::
 
@@ -451,7 +453,7 @@ shell
 
 The shell module takes the command name followed by a list of
 arguments, space delimited.  It is almost exactly like the command module
-but runs the command through the shell rather than directly.
+but runs the command through the user's configured shell on the remote node.
 
 The given command will be executed on all selected nodes.  
 

rst/playbooks.rst

@@ -501,6 +501,12 @@ To save some typing, repeated tasks can be written in short-hand like so::
          - testuser1
          - testuser2
 
+The above would be the equivalent of::
+
+    - name: add user testuser1
+      action: user name=testuser1 state=present groups=wheel
+    - name: add user testuser2
+      action: user name=testuser2 state=present groups=wheel
 
 Asynchronous Actions and Polling
 ++++++++++++++++++++++++++++++++