diff --git a/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc b/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
index 0d57b5bd2d1..12da352b51c 100644
--- a/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
+++ b/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
@@ -45,20 +45,20 @@ The following is a sample format of the file:
 
 [source,js]
 --------------------------------------------------
-# blank lines and lines starting with pound are comments.
+# Blank lines and lines starting with pound are comments.
 
-#Explicit mappings match any token sequence on the LHS of "=>"
-#and replace with all alternatives on the RHS.  These types of mappings
-#ignore the expand parameter in the schema.
-#Examples:
+# Explicit mappings match any token sequence on the LHS of "=>"
+# and replace with all alternatives on the RHS.  These types of mappings
+# ignore the expand parameter in the schema.
+# Examples:
 i-pod, i pod => ipod,
 sea biscuit, sea biscit => seabiscuit
 
-#Equivalent synonyms may be separated with commas and give
-#no explicit mapping.  In this case the mapping behavior will
-#be taken from the expand parameter in the schema.  This allows
-#the same synonym file to be used in different synonym handling strategies.
-#Examples:
+# Equivalent synonyms may be separated with commas and give
+# no explicit mapping.  In this case the mapping behavior will
+# be taken from the expand parameter in the schema.  This allows
+# the same synonym file to be used in different synonym handling strategies.
+# Examples:
 ipod, i-pod, i pod
 foozball , foosball
 universe , cosmos
@@ -70,10 +70,10 @@ ipod, i-pod, i pod => ipod, i-pod, i pod
 # to the explicit mapping:
 ipod, i-pod, i pod => ipod
 
-#multiple synonym mapping entries are merged.
+# Multiple synonym mapping entries are merged.
 foo => foo bar
 foo => baz
-#is equivalent to
+# is equivalent to
 foo => foo bar, baz
 --------------------------------------------------
 
@@ -96,7 +96,7 @@ configuration file (note use of `synonyms` instead of `synonyms_path`):
 --------------------------------------------------
 
 However, it is recommended to define large synonyms set in a file using
-`synonyms_path`.
+`synonyms_path`, because specifying them inline increases cluster size unnecessarily.
 
 [float]
 ==== WordNet synonyms