Nick Coghlan <ncoghlan@gmail.com> added the comment: My specific suggestion is to have a dedicated "Quick Reference" section before the first example. This section would be aimed at two groups of people: - those wanting a quick overview of the features argparse offers them ("This looks complicated, what can it do for me?") - those wanting a reminder of the exact spelling of various items ("I know what I want to do, and I know argparse can do it because I've done it before, but how do I tell argparse exactly what I want?") Since the heart of argparse is the ability to map arguments to actions, I'd suggest the quick reference section actually lead with a table of "actions" that argparse natively supports, along with a final entry pointing to the information on custom actions (i.e. subclasses of argparse.Action). Likely columns for this first table: Action Name, Description, Parameters The "Parameters" column would span multiple lines, with one parameter and a brief description of the parameter on each line. The second table could then just be a short summary of the various 'nargs' values. Repeating the list of parameters to ArgumentParser in the quick reference section probably isn't necessary, and the short parameter descriptions in the actions table should suffice for add_argument(). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________