diff --git a/config/logstash.yml b/config/logstash.yml
index a04760246a6..99cad344dfa 100644
--- a/config/logstash.yml
+++ b/config/logstash.yml
@@ -25,7 +25,7 @@
 # Set the number of workers that will, in parallel, execute the filters+outputs
 # stage of the pipeline.
 #
-# This defaults to half the number of the host's CPU cores.
+# This defaults to the number of the host's CPU cores.
 #
 # pipeline.workers: 2
 #
diff --git a/docs/static/command-line-flags.asciidoc b/docs/static/command-line-flags.asciidoc
index 678dea29037..1a295ef1356 100644
--- a/docs/static/command-line-flags.asciidoc
+++ b/docs/static/command-line-flags.asciidoc
@@ -1,11 +1,9 @@
 [[command-line-flags]]
-=== Command-line flags
+=== Command-Line Flags
 
 Logstash has the following flags. You can use the `--help` flag to display this information.
 
-As an alternative to setting command-line flags, you can specify options in the Logstash settings file,
-`logstash.yml`, located in `LOGSTASH_HOME/config`. Any flags that you set at the command line override the corresponding
-options in the `logstash.yml` file. 
+You can also control Logstash execution by specifying options in the Logstash settings file. For more info, see <<logstash-settings-file>>.  
 
 coming[5.0.0-alpha3, Command-line flags have dots instead of dashes in their names]
 
@@ -20,13 +18,10 @@ coming[5.0.0-alpha3, Command-line flags have dots instead of dashes in their nam
  is specified, `stdout { codec => rubydebug }}` is default.
 
 *`-w, --pipeline.workers COUNT`*::
- Sets the number of pipeline workers (threads) to run for filter processing (default: half the number of cores).
+ Sets the number of pipeline workers (threads) to run for filter processing (default: the number of cores).
  If you find that events are backing up, or that the CPU is not saturated, consider increasing
  this number to better utilize machine processing power.
  
-*`--pipeline.output.workers COUNT`*::
- Sets the number of pipeline workers (threads) to run for each output plugin instance.
-
 *`-b, --pipeline.batch.size SIZE`*::
  This parameter defines the maximum number of events an individual worker thread will collect
  before attempting to execute its filters and outputs. Default is 125 events.
@@ -84,8 +79,8 @@ coming[5.0.0-alpha3, Command-line flags have dots instead of dashes in their nam
   Web API http port (default: 9600)
 
 *`--pipeline.unsafe_shutdown`*::
-  Force logstash to exit during shutdown even if there are still inflight events
-  in memory. By default, logstash will refuse to quit until all received events
+  Force Logstash to exit during shutdown even if there are still inflight events
+  in memory. By default, Logstash will refuse to quit until all received events
   have been pushed to the outputs.
 
 *`-h, --help`*::
diff --git a/docs/static/settings-file.asciidoc b/docs/static/settings-file.asciidoc
new file mode 100644
index 00000000000..748b0e79c4d
--- /dev/null
+++ b/docs/static/settings-file.asciidoc
@@ -0,0 +1,31 @@
+[[logstash-settings-file]]
+=== Settings File
+
+coming[5.0.0-alpha3]
+
+You can set options in the Logstash settings file, `logstash.yml`, to control Logstash execution. Each setting in the
+`logstash.yml` file corresponds to a <<command-line-flags,command-line flag>>. 
+
+Any flags that you set at the command line override the corresponding settings in the `logstash.yml` file. 
+
+The `logstash.yml` file, which is written in http://http://yaml.org/[YAML], is located in `LOGSTASH_HOME/config`. You can
+specify settings in hierarchical form or use flat keys. For example, to use hierarchical form to set the pipeline batch
+size and batch delay, you specify:
+
+[source,yaml]
+-------------------------------------------------------------------------------------
+pipeline:
+  batch:
+    size: 125
+    delay: 5
+-------------------------------------------------------------------------------------
+
+To express the same values as flat keys, you specify:
+
+[source,yaml]
+-------------------------------------------------------------------------------------
+pipeline.batch.size: 125
+pipeline.batch.delay: 5
+-------------------------------------------------------------------------------------
+
+See <<command-line-flags>> for a description of the available options.