diff --git a/docs/api.md b/docs/api.md
index 9b8829137..d7eeb9e2b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -914,7 +914,7 @@ To submit a new translation for yargs:
 <a name="middleware"></a>.middleware(callbacks, [applyBeforeValidation])
 ------------------------------------
 
-Define global middleware functions to be called first, in list order, for all cli command.  
+Define global middleware functions to be called first, in list order, for all cli command.
 
 The `callbacks` parameter can be a function or a list of functions.  Each callback gets passed a reference to argv.
 
@@ -1291,12 +1291,12 @@ Generate a bash completion script. Users of your application can install this
 script in their `.bashrc`, and yargs will provide completion shortcuts for
 commands and options.
 
-.showHelp(consoleLevel='error')
+.showHelp([consoleLevel | printCallback])
 ---------------------------
 
-Print the usage data using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel` for printing.
+Print the usage data.
 
-Example:
+If no argument is provided, usage data is printed using `console.error`.
 
 ```js
 var yargs = require("yargs")
@@ -1304,12 +1304,18 @@ var yargs = require("yargs")
 yargs.showHelp(); //prints to stderr using console.error()
 ```
 
-Or, to print the usage data to `stdout` instead, you can specify the use of `console.log`:
+If a string is specified, usage data is printed using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel`.
 
 ```js
 yargs.showHelp("log"); //prints to stdout using console.log()
 ```
 
+If a function is specified, it is called with a single argument - the usage data as a string.
+
+```js
+yargs.showHelp(s => myStream.write(s)); //prints to myStream
+```
+
 Later on, `argv` can be retrieved with `yargs.argv`.
 
 .showHelpOnFail(enable, [message])
diff --git a/test/usage.js b/test/usage.js
index 75918acd7..37052714d 100644
--- a/test/usage.js
+++ b/test/usage.js
@@ -2414,7 +2414,27 @@ describe('usage tests', () => {
       ])
     })
 
-    it('should call the correct console.log method', () => {
+    it('should print the help using console.error when no arguments were specified', () => {
+      const r = checkUsage(() => {
+        const y = yargs(['--foo'])
+          .options('foo', {
+            alias: 'f',
+            describe: 'foo option'
+          })
+          .wrap(null)
+
+        y.showHelp()
+      })
+
+      r.errors.join('\n').split(/\n+/).should.deep.equal([
+        'Options:',
+        '  --help     Show help  [boolean]',
+        '  --version  Show version number  [boolean]',
+        '  --foo, -f  foo option'
+      ])
+    })
+
+    it('should call the correct console.log method when specified', () => {
       const r = checkUsage(() => {
         const y = yargs(['--foo'])
           .options('foo', {
@@ -2435,7 +2455,7 @@ describe('usage tests', () => {
       ])
     })
 
-    it('should provide a help string to handler when provided', (done) => {
+    it('should call the callback to print when specified', (done) => {
       const y = yargs(['--foo'])
         .options('foo', {
           alias: 'f',
@@ -2443,8 +2463,8 @@ describe('usage tests', () => {
         })
         .wrap(null)
 
-      y.showHelp(testHandler)
-      function testHandler (msg) {
+      y.showHelp(printCallback)
+      function printCallback (msg) {
         msg.split(/\n+/).should.deep.equal([
           'Options:',
           '  --help     Show help  [boolean]',