Add docs describing some additional behaviors around modules

docs/docsite/rst/dev_guide/developing_modules.rst

@@ -53,6 +53,16 @@ For more information about action plugins, `read the action plugins documentatio
 
 Check out the roles documentation `available here <http://docs.ansible.com/ansible/playbooks_reuse_roles.html#roles>`_.
 
+5. Should you write multiple modules instead of one module?
+
+The following guidelines will help you determine if your module attempts to do too much, and should likely be broken into several smaller modules.
+
+* Modules should have a concise and well defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
+
+* Modules should not require that a user know all the underlying options of an api/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected.
+
+* Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API.
+
 
 .. _developing_modules_all:
 

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -26,6 +26,11 @@ and guidelines:
 
 * As results from many hosts will be aggregated at once, modules should return only relevant output.  Returning the entire contents of a log file is generally bad form.
 
+* Modules should have a concise and well defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
+
+* Modules should not require that a user know all the underlying options of an api/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected.
+
+* Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API.
 
 .. _debugging_ansiblemodule_based_modules:
 
@@ -190,4 +195,4 @@ Avoid creating a module that does the work of other modules; this leads to code
 Avoid creating 'caches'. Ansible is designed without a central server or authority, so you cannot guarantee it will not run with different permissions, options or locations. If you need a central authority, have it on top of Ansible (for example, using bastion/cm/ci server or tower); do not try to build it into modules.
 
 Always use the hacking/test-module script when developing modules and it will warn
-you about these kind of things.
+you about these kind of things.