Finish migration documentation for #719

1 files changed, 58 insertions, 2 deletions

diff --git a/docs/migrating/next_steps.rst b/docs/migrating/next_steps.rst
index 3f560501..f43c69c9 100644
--- a/docs/migrating/next_steps.rst
+++ b/docs/migrating/next_steps.rst
@@ -1,6 +1,62 @@
 Next Steps
 ==========
 
-What features (with links to details) are easy to implement next
+Once your current application is using ``cmd2``, you can start to expand the
+functionality by levering other ``cmd2`` features. The three ideas here will
+get you started. Browse the rest of the :ref:`features/index:Features` to see
+what else ``cmd2`` can help you do.
 
-:doc:`Help <../features/help>`
+
+Argument Parsing
+----------------
+
+For all but the simplest of commands, it's probably easier to use `argparse
+<https://docs.python.org/3/library/argparse.html>`_ to parse user input.
+``cmd2`` provides a ``@with_argparser()`` decorator which associates an
+``ArgumentParser`` object with one of your commands. Using this method will:
+
+1. Pass your command a `Namespace
+<https://docs.python.org/3/library/argparse.html#argparse.Namespace>`_
+containing the arguments instead of a string of text.
+
+2. Properly handle quoted string input from your users.
+
+3. Create a help message for you based on the ``ArgumentParser``.
+
+4. Give you a big headstart adding :ref:`features/completion:Completion` to
+   your application.
+
+5. Make it much easier to implement subcommands (i.e. ``git`` has
+   a bunch of subcommands such as ``git pull``, ``git diff``, etc).
+
+There's a lot more about :ref:`features/argument_processing:Argument
+Processing` if you want to dig in further.
+
+
+Help
+----
+
+If you have lot of commands in your application, ``cmd2`` can categorize those
+commands using a one line decorator ``@with_category()``. When a user types
+``help`` the available commands will be organized by the category you
+specified.
+
+If you were already using ``argparse`` or decided to switch to it, you can
+easily :ref:`standardize all of your help messages
+<features/argument_processing:Help Messages>` to be generated by your argument
+parsers and displayed by ``cmd2``. No more help messages that don't match what
+the code actually does.
+
+
+Generating Output
+-----------------
+
+If your program generates output by printing directly to ``sys.stdout``, you
+should consider switching to :meth:`cmd2.cmd2.Cmd.poutput`,
+:meth:`cmd2.cmd2.Cmd.perror`, and :meth:`cmd2.cmd2.Cmd.pfeedback`. These
+methods work with several of the built in :ref:`features/settings:Settings` to
+allow the user to view or suppress feedback (i.e. progress or status output).
+They also properly handle ansi colored output according to user preference.
+Speaking of colored output, you can use any color library you want, or use the
+included :meth:`cmd2.ansi.style` function. These and other related topics are
+covered in :ref:`features/generating_output:Generating Output`.