diff --git a/lib/smart_proxy_dynflow/runner/command.rb b/lib/smart_proxy_dynflow/runner/command.rb
index 7ef7605..6a55084 100644
--- a/lib/smart_proxy_dynflow/runner/command.rb
+++ b/lib/smart_proxy_dynflow/runner/command.rb
@@ -1,5 +1,18 @@
 module Proxy::Dynflow
   module Runner
+    # This module expects to be included into a Runner action, where it can be
+    # used to simplify handling of long-running processes. However it tracks the
+    # running process as a group of instance variables, which has served us
+    # reasonably well in the past, but can be rather error prone.
+    #
+    # A better alternative to this is
+    # {::Proxy::Dynflow::Runner::ProcessManagerCommand}. It tracks the whole
+    # execution of a process under a single instance variable and uses a more
+    # robust {::Proxy::Dynflow::ProcessManager} under the hood. It also
+    # maintains the same interface and can be used as a drop-in replacement.
+    #
+    # This module is now soft-deprecated and
+    # {::Proxy::Dynflow::Runner::ProcessManagerCommand} should be used instead.
     module Command
       def initialize_command(*command)
         @command_out, @command_in, @command_pid = PTY.spawn(*command)
diff --git a/lib/smart_proxy_dynflow/runner/command_runner.rb b/lib/smart_proxy_dynflow/runner/command_runner.rb
index bb6453d..2751419 100644
--- a/lib/smart_proxy_dynflow/runner/command_runner.rb
+++ b/lib/smart_proxy_dynflow/runner/command_runner.rb
@@ -4,6 +4,7 @@
 
 module Proxy::Dynflow
   module Runner
+    # This class is now soft-deprecated, see {::Proxy::Dynflow::Runner::Command}
     class CommandRunner < Base
       include Command
     end
diff --git a/lib/smart_proxy_dynflow/runner/process_manager_command.rb b/lib/smart_proxy_dynflow/runner/process_manager_command.rb
index cf84c0e..169ac6b 100644
--- a/lib/smart_proxy_dynflow/runner/process_manager_command.rb
+++ b/lib/smart_proxy_dynflow/runner/process_manager_command.rb
@@ -2,6 +2,12 @@
 
 module Proxy::Dynflow
   module Runner
+    # A convenience module which should be included into a Runner action. It
+    # leverages {::Proxy::Dynflow::ProcessManager} to reliably keep track of
+    # an external process and collect its output.
+    #
+    # The only expectation from the Runner action is to call
+    # {#initialize_command} somewhere and pass the command to be run to it.
     module ProcessManagerCommand
       def initialize_command(*command)
         @process_manager = ProcessManager.new(command)