diff --git a/README.md b/README.md
index 58e83c513..eedd014ac 100644
--- a/README.md
+++ b/README.md
@@ -412,43 +412,36 @@ A flag can also be assigned locally which will only apply to that specific comma
 RootCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")
 ```
 
-### Positional Arguments
-
-Validation of positional arguments can be specified using the `Args` field, which accepts
-one of the following values:
-
-- `NoArgs` - the command will report an error if there are any positional args.
-- `ArbitraryArgs` - the command will accept any args.
-- `OnlyValidArgs` - the command will report an error if there are any positiona 
-  args that are not in the `ValidArgs` list.
-- `MinimumNArgs(int)` - the command will report an error if there are not at 
-  least N positional args.
-- `MaximumNArgs(int)` - the command will report an error if there are more than 
-  N positional args.
-- `ExactArgs(int)` - the command will report an error if there are not 
-  exactly N positional args.
-- `RangeArgs(min, max)` - the command will report an error if the number of args 
-  is not between the minimum and maximum number of expected args.
-
-By default, `Args` uses the following legacy behaviour:
-- root commands with no subcommands can take arbitrary arguments
-- root commands with subcommands will do subcommand validity checking
-- subcommands will always accept arbitrary arguments and do no subsubcommand validity checking
+### Positional and Custom Arguments
 
+Validation of positional arguments can be specified using the `Args` field. A
+custom validator can be provided like this:
 
 ```go
-var HugoCmd = &cobra.Command{
-    Use:   "hugo",
-    Short: "Hugo is a very fast static site generator",
-    ValidArgs: []string{"one", "two"}
-    Args: cobra.OnlyValidArgs
-    Run: func(cmd *cobra.Command, args []string) {
-        // args will only have the values one, two
-        // or the cmd.Execute() will fail.
-    },
+
+Args: func validColorArgs(cmd *cobra.Command, args []string) error {
+  if err := cli.RequiresMinArgs(1)(cmd, args); err != nil {
+    return err
+  }
+  if myapp.IsValidColor(args[0]) {
+     return nil
+  }
+  return fmt.Errorf("Invalid color specified: %s", args[0])
 }
+
 ```
 
+The follow validators are built in:
+
+- NoArgs - the command will report an error if there are any positional args.
+- ArbitraryArgs - the command will accept any args.
+- OnlyValidArgs - the command will report an error if there are any positiona args that are not in the ValidArgs list.
+- MinimumNArgs(int) - the command will report an error if there are not at least N positional args.
+- MaximumNArgs(int) - the command will report an error if there are more than N positional args.
+- ExactArgs(int) - the command will report an error if there are not exactly N positional args.
+- RangeArgs(min, max) - the command will report an error if the number of args is not between the minimum and maximum number of expected args.
+
+
 ## Example
 
 In the example below, we have defined three commands. Two are at the top level