diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7006d782..30d57ded 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ appear at the top.
 
   * Add your entries below here, remember to credit yourself however you want
     to be credited!
+  * Removed broken support for setting output to an IO (See #243). @robd
+    * Use `SSHKit.config.output = SSHKit::Formatter::SimpleText.new($stdin)` instead
   * Added support for :interaction_handler option on commands. @robd
   * Removed partially supported 'trace' log level. @robd
   * No longer strip whitespace or newlines in `capture` method on Netssh backend. @robd
diff --git a/EXAMPLES.md b/EXAMPLES.md
index d12ad7a0..902a1fce 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -206,23 +206,41 @@ on hosts do
 end
 ```
 
-## Redirect all output to `/dev/null`
+## Change the output formatter
 
 ```ruby
-SSHKit.config.output = File.open('/dev/null')
+# The default format is pretty, which outputs colored text
+SSHKit.config.format = :pretty
+
+# Text with no coloring
+SSHKit.config.format = :simpletext
+
+# Red / Green dots for each completed step
+SSHKit.config.format = :dot
+
+# No output
+SSHKit.config.format = :blackhole
 ```
 
 ## Implement a dirt-simple formatter class
 
 ```ruby
-class MyFormatter < SSHKit::Formatter::Abstract
-  def write(obj)
-    case obj.is_a? SSHKit::Command
-      # Do something here, see the SSHKit::Command documentation
+module SSHKit
+  module Formatter
+    class MyFormatter < SSHKit::Formatter::Abstract
+      def write(obj)
+        case obj.is_a? SSHKit::Command
+          # Do something here, see the SSHKit::Command documentation
+        end
+      end
     end
   end
 end
 
+# If your formatter is defined in the SSHKit::Formatter module configure with the format option:
+SSHKit.config.format = :myformatter
+
+# Or configure the output directly
 SSHKit.config.output = MyFormatter.new($stdout)
 SSHKit.config.output = MyFormatter.new(SSHKit.config.output)
 SSHKit.config.output = MyFormatter.new(File.open('log/deploy.log', 'wb'))
diff --git a/README.md b/README.md
index 14963a94..cb50ab5a 100644
--- a/README.md
+++ b/README.md
@@ -355,23 +355,32 @@ By default, the output format is set to `:pretty`:
 SSHKit.config.format = :pretty
 ```
 
-However, if you prefer minimal output, `:dot` format will simply output red or green dots based on the success or failure of operations.
+However, if you prefer non colored text you can use the `:simpletext` formatter. If you want minimal output,
+there is also a `:dot` formatter which will simply output red or green dots based on the success or failure of operations.
+There is also a `:blackhole` formatter which does not output anything.
 
-To output directly to $stdout without any formatting, you can use:
+By default, formatters log to `$stdout`, but they can be constructed on any `IO`:
 
 ```ruby
-SSHKit.config.output = $stdout
+# Output to a StringIO:
+out = StringIO.new
+SSHKit.config.output = SSHKit::Formatter::Pretty.new(out)
+# Do something with out.string
+
+# Or output to a file:
+SSHKit.config.output = SSHKit::Formatter::SimpleText.new(File.open('log/deploy.log', 'wb'))
 ```
 
 #### Custom formatters
 
 Want custom output formatting? Here's what you have to do:
 
-1. Write a new formatter class in the `SSHKit::Formatter` namespace. As an example, check out the default [pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
-1. Set the output format as described above. E.g. if your new formatter is called `Foobar`:
-
-        SSHKit.config.format = :foobar
+1. Write a new formatter class in the `SSHKit::Formatter` module. As an example, check out the default [pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
+1. Set the output format as described above. E.g. if your new formatter is called `FooBar`:
 
+```ruby
+SSHKit.config.format = :foobar
+```
 
 ## Output Verbosity