Create a considerations section

Instead of having the considerations and best practices that
should be used when developing with this library scattered
across a few different links and pages combine these together
into a single section in the developer documentation. As a
side-effect of this change remove the documenation about the
utils to use and not use and just refer those to use the modules,
classes and APIs described in these documents.

Change-Id: I20e1405cb6ecb654baa29812b98ada7bdc393f6c

doc/source/index.rst

@@ -33,6 +33,30 @@ Contents
 
    workers
 
+Considerations
+--------------
+
+Things to consider before (and during) development and integration with
+TaskFlow into your project:
+
+* Read over the `paradigm shifts`_ and engage the team in `IRC`_ (or via the
+  `openstack-dev`_ mailing list) if these need more explanation (prefix
+  ``[TaskFlow]`` to your emails subject to get an even faster response).
+* Follow (or at least attempt to follow) some of the established
+  `best practices`_ (feel free to add your own suggested best practices).
+
+.. warning::
+
+        External usage of internal helpers and other internal utility functions
+        and modules should be kept to a *minimum* as these may be altered,
+        refactored or moved *without* notice. If you are unsure whether to use
+        a function, class, or module, please ask (see above).
+
+.. _IRC: irc://chat.freenode.net/openstack-state-management
+.. _best practices: http://wiki.openstack.org/wiki/TaskFlow/Best_practices
+.. _paradigm shifts: http://wiki.openstack.org/wiki/TaskFlow/Paradigm_shifts
+.. _openstack-dev: mailto:openstack-dev@lists.openstack.org
+
 Miscellaneous
 -------------
 
@@ -40,7 +64,6 @@ Miscellaneous
    :maxdepth: 2
 
    exceptions
-   utils
    states
    examples
 

doc/source/utils.rst

@@ -1,15 +0,0 @@
------
-Utils
------
-
-.. warning::
-
-        External usage of internal helpers and other internal utility functions
-        and modules should be kept to a *minimum* as these may be altered,
-        refactored or moved *without* notice.
-
-The following classes and modules though may be used:
-
-.. autoclass:: taskflow.utils.misc.Failure
-.. autoclass:: taskflow.utils.eventlet_utils.GreenExecutor
-.. automodule:: taskflow.utils.persistence_utils