diff --git a/README.md b/README.md
index f937677..32e7f00 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,10 @@ Think ShellJS is cool? Check out some related projects (like
 [cash](https://github.com/dthree/cash)--a javascript-based POSIX shell)
 in our [Wiki page](https://github.com/shelljs/shelljs/wiki)!
 
+Upgrading from an older version? Check out our [breaking
+changes](https://github.com/shelljs/shelljs/wiki/Breaking-Changes) page to see
+what changes to watch out for while upgrading.
+
 ## Command line use
 
 If you just want cross platform UNIX commands, checkout our new project
@@ -546,9 +550,9 @@ exec('some_long_running_process', function(code, stdout, stderr) {
 ```
 
 Executes the given `command` _synchronously_, unless otherwise specified.  When in synchronous
-mode returns the object `{ code:..., stdout:... , stderr:... }`, containing the program's
-`stdout`, `stderr`, and its exit `code`. Otherwise returns the child process object,
-and the `callback` gets the arguments `(code, stdout, stderr)`.
+mode, this returns a ShellString (compatible with ShellJS v0.6.x, which returns an object
+of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
+object, and the `callback` gets the arguments `(code, stdout, stderr)`.
 
 **Note:** For long-lived processes, it's best to run `exec()` asynchronously as
 the current synchronous implementation uses a lot of CPU. This should be getting
diff --git a/src/exec.js b/src/exec.js
index 734e37b..74aef2e 100644
--- a/src/exec.js
+++ b/src/exec.js
@@ -218,9 +218,9 @@ function execAsync(cmd, opts, pipe, callback) {
 //@ ```
 //@
 //@ Executes the given `command` _synchronously_, unless otherwise specified.  When in synchronous
-//@ mode returns the object `{ code:..., stdout:... , stderr:... }`, containing the program's
-//@ `stdout`, `stderr`, and its exit `code`. Otherwise returns the child process object,
-//@ and the `callback` gets the arguments `(code, stdout, stderr)`.
+//@ mode, this returns a ShellString (compatible with ShellJS v0.6.x, which returns an object
+//@ of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
+//@ object, and the `callback` gets the arguments `(code, stdout, stderr)`.
 //@
 //@ **Note:** For long-lived processes, it's best to run `exec()` asynchronously as
 //@ the current synchronous implementation uses a lot of CPU. This should be getting