diff --git a/logstash-core/lib/logstash/plugin.rb b/logstash-core/lib/logstash/plugin.rb
index 1e8334b00..841a39e2b 100644
--- a/logstash-core/lib/logstash/plugin.rb
+++ b/logstash-core/lib/logstash/plugin.rb
@@ -19,19 +19,20 @@ class LogStash::Plugin
   # for a specific plugin.
   config :enable_metric, :validate => :boolean, :default => true
 
-  # Add a unique `ID` to the plugin instance, this `ID` is used for tracking
-  # information for a specific configuration of the plugin.
+  # Add a unique `ID` to the plugin configuration. If no ID is specified, Logstash will generate one. 
+  # It is strongly recommended to set this ID in your configuration. This is particulary useful 
+  # when you have two or more plugins of the same type, for example, if you have 2 grok filters. 
+  # Adding a named ID in this case will help in monitoring Logstash when using the monitoring APIs.
   #
   # [source,ruby]
   # ---------------------------------------------------------------------------------------------------
   # output {
   #  stdout {
-  #    id => "ABC"
+  #    id => "my_plugin_id"
   #  }
   # }
   # ---------------------------------------------------------------------------------------------------
   #
-  # If you don't explicitely set this variable Logstash will generate a unique name.
   config :id, :validate => :string
 
   def hash
diff --git a/tools/logstash-docgen/templates/plugin-doc.asciidoc.erb b/tools/logstash-docgen/templates/plugin-doc.asciidoc.erb
index a9c9933dc..aff6deb53 100644
--- a/tools/logstash-docgen/templates/plugin-doc.asciidoc.erb
+++ b/tools/logstash-docgen/templates/plugin-doc.asciidoc.erb
@@ -1,9 +1,9 @@
 [[plugins-<%= section %>s-<%= name %>]]
 === <%= name %>
 
-Version: <%=version%>
-Released on: <%=release_date%>
-<%=changelog_url%>[Changelog]
+* Version: <%=version%>
+* Released on: <%=release_date%>
+* <%=changelog_url%>[Changelog]
 
 <% unless default_plugin? %>
 NOTE: This plugin does not ship with Logstash by default, but it is easy to install by running `bin/logstash-plugin install logstash-<%= section %>-<%= name %>`.