diff --git a/doc/03-cli.md b/doc/03-cli.md
index 855fca837..4648aa42a 100644
--- a/doc/03-cli.md
+++ b/doc/03-cli.md
@@ -39,11 +39,9 @@ resolution.
 * **--dry-run:** If you want to run through an installation without actually
   installing a package, you can use `--dry-run`. This will simulate the
   installation and show you what would happen.
-* **--no-install-recommends:** By default composer will install all packages
-  that are referenced by `recommend`. By passing this option you can disable
-  that.
-* **--install-suggests:** The packages referenced by `suggest` will not be
-  installed by default. By passing this option, you can install them.
+* **--dev:** By default composer will only install required packages. By
+  passing this option you can also make it install packages referenced by
+  `require-dev`.
 
 ## update
 
@@ -59,8 +57,7 @@ into `composer.lock`.
 
 * **--prefer-source:** Install packages from `source` when available.
 * **--dry-run:** Simulate the command without actually doing anything.
-* **--no-install-recommends:** Do not install packages referenced by `recommend`.
-* **--install-suggests:** Install packages referenced by `suggest`.
+* **--dev:** Install packages listed in `require-dev`.
 
 ## search
 
@@ -111,8 +108,8 @@ specific version.
 ## depends
 
 The `depends` command tells you which other packages depend on a certain
-package. You can specify which link types (`require`, `recommend`, `suggest`)
-should be included in the listing.
+package. You can specify which link types (`require`, `require-dev`)
+should be included in the listing. By default both are used.
 
     $ php composer.phar depends --link-type=require monolog/monolog
 
diff --git a/doc/04-schema.md b/doc/04-schema.md
index 5886608e6..2b7aef879 100644
--- a/doc/04-schema.md
+++ b/doc/04-schema.md
@@ -41,7 +41,7 @@ Required for published packages (libraries).
 
 A short description of the package. Usually this is just one line long.
 
-Optional but recommended.
+Required for published packages (libraries).
 
 ### version
 
@@ -165,14 +165,13 @@ An example:
 
 Optional, but highly recommended.
 
-### Link types <span>(require, recommend, suggest, replace, provide)</span>
+### Package links <span>(require, require-dev, conflict, replace, provide)</span>
 
 Each of these takes an object which maps package names to version constraints.
 
 * **require:** Packages required by this package.
-* **recommend:** Recommended packages, installed by default.
-* **suggest:**  Suggested packages. These are displayed after installation,
-  but not installed by default.
+* **require-dev:** Packages required for developing this package, or running
+  tests, etc. They are installed if install or update is ran with `--dev`.
 * **conflict:** Mark this version of this package as conflicting with other
   packages.
 * **replace:** Packages that can be replaced by this package. This is useful
@@ -193,6 +192,24 @@ Example:
 
 Optional.
 
+### suggest
+
+Suggested packages that can enhance or work well with this package. These are
+just informational and are displayed after the package is installed, to give
+your users a hint that they could add more packages, even though they are not
+strictly required.
+
+The format is like package links above, except that the values are free text
+and not version constraints.
+
+Example:
+
+    {
+        "suggest": {
+            "monolog/monolog": "Allows more advanced logging of the application flow"
+        }
+    }
+
 ### autoload
 
 Autoload mapping for a PHP autoloader.