diff --git a/docs/source/notebook/nbconvert.rst b/docs/source/notebook/nbconvert.rst
index 446ae66..955bc50 100644
--- a/docs/source/notebook/nbconvert.rst
+++ b/docs/source/notebook/nbconvert.rst
@@ -78,18 +78,44 @@ The currently supported export formats are:
   Basic reStructuredText output. Useful as a starting point for embedding notebooks
   in Sphinx docs.
 
-* ``--to python``
+* ``--to script``
 
-  Convert a notebook to an executable Python script.
-  This is the simplest way to get a Python script out of a notebook.
-  If there were any magics in the notebook, this may only be executable from
+  Convert a notebook to an executable script.
+  This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
+  If there were any magics in an IPython notebook, this may only be executable from
   an IPython session.
+
+* ``--to notebook``
+
+  .. versionadded:: 3.0
+  
+  This doesn't convert a notebook to a different format *per se*,
+  instead it allows the running of nbconvert preprocessors on a notebook,
+  and/or conversion to other notebook formats. For example::
+  
+      ipython nbconvert --to notebook --execute mynotebook.ipynb
+  
+  will open the notebook, execute it, capture new output, and save the result in
+  :file:`mynotebook.nbconvert.ipynb`.
+  
+  ::
+  
+      ipython nbconvert --to notebook --nbformat 3 mynotebook
+  
+  will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
+  in version 3 of the :ref:`notebook format <nbformat>`.
+  
+  If you want to convert a notebook in-place,
+  you can specify the ouptut file to be the same as the input file::
+  
+      ipython nbconvert --to notebook mynb --output mynb
+  
+  Be careful with that, since it will replace the input file.
   
 .. note::
 
   nbconvert uses pandoc_ to convert between various markup languages,
-  so pandoc is a dependency of most nbconvert transforms,
-  excluding Markdown and Python.
+  so pandoc is a dependency when converting to latex or reStructuredText.
 
 .. _pandoc: http://johnmacfarlane.net/pandoc/
 
diff --git a/docs/source/whatsnew/version3.rst b/docs/source/whatsnew/version3.rst
index e0b80bd..fd6d1f1 100644
--- a/docs/source/whatsnew/version3.rst
+++ b/docs/source/whatsnew/version3.rst
@@ -219,7 +219,7 @@ Backwards incompatible changes
 
   You can downgrade a notebook to v3 via ``nbconvert``::
   
-      ipython nbconvert --to notebook --nbformat 3 [notebook]
+      ipython nbconvert --to notebook --nbformat 3 <notebook>
   
   which will create :file:`notebook.v3.ipynb`, a copy of the notebook in v3 format.