Re-order items to be more logical.

docs/migrate-v1-to-v2.md

@@ -1,6 +1,16 @@
 Migration Guide: v1 to v2
 ===
 
+
+v2 has a number of breaking changes but converting is relatively
+straightforward: make the changes documented below then resolve any
+compiler errors. We hope this will be sufficient for most typical
+users.
+
+If you find any issues not covered by this document, please post a
+comment on [Issue 921](https://github.com/urfave/cli/issues/921) or
+consider sending a PR to help improve this guide.
+
 <!-- toc -->
 
   * [Flags before args](#flags-before-args)
@@ -16,15 +26,6 @@ Migration Guide: v1 to v2
 
 <!-- tocstop -->
 
-v2 has a number of breaking changes but converting is relatively
-straightforward: make the changes documented below then resolve any
-compiler errors. We hope this will be sufficient for most typical
-users.
-
-If you find any issues not covered by this document, please post a
-comment on [Issue 921](https://github.com/urfave/cli/issues/921) or
-consider sending a PR to help improve this guide.
-
 # Flags before args
 
 In v2 flags must come before args. This is more POSIX-compliant.  You
@@ -72,38 +73,17 @@ cli.StringFlag{
 
 Sadly v2 doesn't warn you if a comma is in the name.
 
-# Commands are now lists of pointers
-
-Occurrences of `[]Command` have been changed to `[]*Command`.
-
-What this means to you:
-
-Look for `[]cli.Command{}` and change it to `[]*cli.Command{}`
-
-Example:
-
-* OLD: `var commands = []cli.Command{}`
-* NEW: `var commands = []*cli.Command{}`
-
-Compiler messages you might see:
-
-```
-cannot convert commands (type []cli.Command) to type cli.CommandsByName
-cannot use commands (type []cli.Command) as type []*cli.Command in assignment
-```
-
-# Lists of commands should be pointers
+# Actions returns errors
 
-If you are building up a list of commands, the individual items should
-now be pointers.
+A command's `Action:` now returns an `error`.
 
-* OLD: `cli.Command{`
-* NEW: `&cli.Command{`
+* OLD: `Action: func(c *cli.Context) {`
+* NEW: `Action: func(c *cli.Context) error {`
 
 Compiler messages you might see:
 
 ```
-cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to
+cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value
 ```
 
 # cli.Flag changed
@@ -133,31 +113,52 @@ Compiler messages you might see:
 	cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver)
 ```
 
-# Appending Commands
+# Commands are now lists of pointers
 
-Appending to a list of commands needs to be changed since the list is
-now pointers.
+Occurrences of `[]Command` have been changed to `[]*Command`.
 
-* OLD: `commands = append(commands, *c)`
-* NEW: `commands = append(commands, c)`
+What this means to you:
+
+Look for `[]cli.Command{}` and change it to `[]*cli.Command{}`
+
+Example:
+
+* OLD: `var commands = []cli.Command{}`
+* NEW: `var commands = []*cli.Command{}`
 
 Compiler messages you might see:
 
 ```
-cannot use c (type *cli.Command) as type cli.Command in append
+cannot convert commands (type []cli.Command) to type cli.CommandsByName
+cannot use commands (type []cli.Command) as type []*cli.Command in assignment
 ```
 
-# Actions returns errors
+# Lists of commands should be pointers
 
-A command's `Action:` now returns an `error`.
+If you are building up a list of commands, the individual items should
+now be pointers.
 
-* OLD: `Action: func(c *cli.Context) {`
-* NEW: `Action: func(c *cli.Context) error {`
+* OLD: `cli.Command{`
+* NEW: `&cli.Command{`
 
 Compiler messages you might see:
 
 ```
-cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value
+cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to
+```
+
+# Appending Commands
+
+Appending to a list of commands needs to be changed since the list is
+now pointers.
+
+* OLD: `commands = append(commands, *c)`
+* NEW: `commands = append(commands, c)`
+
+Compiler messages you might see:
+
+```
+cannot use c (type *cli.Command) as type cli.Command in append
 ```
 
 # Everything else