diff --git a/doc_src/completions.rst b/doc_src/completions.rst
index c9cd4fac6..c1901b807 100644
--- a/doc_src/completions.rst
+++ b/doc_src/completions.rst
@@ -3,20 +3,24 @@
 Writing your own completions
 ============================
 
-To specify a completion, use the ``complete`` command. ``complete`` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program ``myprog``, one would start the completion command with ``complete -c myprog ...``
+To specify a completion, use the ``complete`` command. ``complete`` takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program ``myprog``, start the completion command with ``complete -c myprog ...``
+
+For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`complete <cmds/complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
 
 To provide a list of possible completions for myprog, use the ``-a`` switch. If ``myprog`` accepts the arguments start and stop, this can be specified as ``complete -c myprog -a 'start stop'``. The argument to the ``-a`` switch is always a single string. At completion time, it will be tokenized on spaces and tabs, and variable expansion, command substitution and other forms of parameter expansion will take place::
 
   # If myprog can list the valid outputs with the list-outputs subcommand:
   complete -c myprog -l output -a '(myprog list-outputs)'
 
-``fish`` has a special syntax to support specifying switches accepted by a command. The switches ``-s``, ``-l`` and ``-o`` are used to specify a short switch (single character, such as ``-l``), a gnu style long switch (such as ``--color``) and an old-style long switch (like ``-shuffle``), respectively. If the command 'myprog' has an option '-o' which can also be written as ``--output``, and which can take an additional value of either 'yes' or 'no', this can be specified by writing::
+``fish`` has a special syntax to support specifying switches accepted by a command. The switches ``-s``, ``-l`` and ``-o`` are used to specify a short switch (single character, such as ``-l``), a gnu style long switch (such as ``--color``) and an old-style long switch (with one ``-``, like ``-shuffle``), respectively. If the command 'myprog' has an option that can be written as ``-o`` or ``--output``, that is::
+
+  complete -c myprog -s o -l output
+
+If this option takes an optional argument, you would also add ``--argument`` or ``-a``, and give that the possible arguments::
 
   complete -c myprog -s o -l output -a "yes no"
 
-For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`complete <cmds/complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
-
-In the complete call above, the ``-a`` arguments apply when the option -o/--output has been given, so this offers them for::
+This offers the arguments "yes" and "no" for::
 
   > myprog -o<TAB>
   > myprog --output=<TAB>
@@ -36,9 +40,7 @@ which offers yes/no in these cases::
   > myprog -o <TAB>
   > myprog --output <TAB>
 
-In the latter two cases, files will also be offered because file completion is enabled by default.
-
-You would either inhibit file completion for a single option::
+Fish will also offer files by default, in addition to the arguments you specified. You would either inhibit file completion for a single option::
 
   complete -c myprog -s o -l output --no-files -ra "yes no"