diff --git a/doc/source/dev/architecture.rst b/doc/source/dev/architecture.rst
index dedcfd4328..3abbd05703 100644
--- a/doc/source/dev/architecture.rst
+++ b/doc/source/dev/architecture.rst
@@ -93,9 +93,20 @@ driver itself or on any interface with driver_periodic_task_ decorator, e.g.
         def task2(self, manager, context):
             pass  # do something
 
+        @base.driver_periodic_task(parallel=False)
+        def blocking_task(self, manager, context):
+            pass  # do something fast, this blocks other tasks from starting!
+
 
 Here ``spacing`` argument is a period for a given periodic task.
 
+The ``parallel`` argument may be passed to driver_periodic_task_ and defaults
+to True. If False, this task will be run in the periodic task loop, rather
+than a separate greenthread. This should be used with caution, as it will
+cause all other periodic tasks to be blocked from starting while the
+non-parallel task is running. Long running tasks, especially any tasks that
+make a remote call (to a BMC, HTTP, etc.) **must** be parallelized.
+
 .. note::
     By default periodic task names are derived from method names,
     so they should be unique within a Python module.