Incorporate review comments

Fixes #9861

docs/static/doc-for-plugin.asciidoc

@@ -3,27 +3,27 @@
 
 Quality documentation with good examples contributes to the adoption of your plugin.
 
-The documentation for your plugin will be generated and published in the
+The documentation that you write for your plugin will be generated and published
-{logstash-ref}/index.html[Logstash Reference] and the
+in the {logstash-ref}/index.html[Logstash Reference] and the
-{lsplugindocs}[Versioned plugin docs].
+{lsplugindocs}[Logstash Versioned Plugin Reference].
 
 [[plugin-doc-file]]
 ==== Documentation file
 
-Documentation should be included in your plugin structure as a single file called 'docs/index.asciidoc'.
+Include documentation in your plugin structure as a single file called 'docs/index.asciidoc'.
 
 [[heading-ids]]
 ==== Heading IDs
 
-Heading IDs must be in a format that supports generated IDs. This approach
+Format heading anchors with variables that can support generated IDs. This approach
-creates unique IDs when the
+creates unique IDs when the {lsplugindocs}[Logstash Versioned Plugin Reference]
-{lsplugindocs}[Versioned plugin docs] are generated.
+is built. Unique heading IDs are required to avoid duplication over multiple versions of a plugin.
 
 *Example*
 
 Don't hardcode a heading ID like this: `[[config_models]]`
 
-Instead, define it like this:
+Instead, use variables to define it:
 
 [source,txt]
 ----------------------------------
@@ -31,9 +31,82 @@ Instead, define it like this:
 ==== Configuration models
 ----------------------------------
 
-If you hardcode an ID, the versioned plugin docs will build correctly the
+If you hardcode an ID, the {lsplugindocs}[Logstash Versioned Plugin Reference]
-first time. The second time the doc build runs, the ID will be flagged as
+builds correctly the first time. The second time the doc build runs, the ID
-a duplicate, and the build will fail.
+is flagged as a duplicate, and the build fails.
+
+
+[[link-format]]
+==== Link formats
+
+Correct link formatting is essential for directing users to the content you
+want them to see. Incorrect link formatting or duplicate links can break the
+documentation build. Let's not do that. 
+
+===== Link to content in the same file
+
+Use angle brackets to format links to content in the same asciidoc file. 
+
+*Example*
+
+This link:
+[source,txt]
+-----
+<<plugins-{type}s-{plugin}-config_models>>
+-----
+
+Points to this heading in the same file:
+
+[source,txt]
+----------------------------------
+[id="plugins-{type}s-{plugin}-config_models"]
+==== Configuration models
+----------------------------------
+
+
+===== Link to content in the Logstash Reference Guide
+
+Use external link syntax for links that point to documentation for other plugins or content in the Logstash Reference Guide.
+
+*Examples*
+[source,txt]
+-----
+{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin]
+-----
+
+[source,txt]
+-----
+{logstash-ref}/getting-started-with-logstash.html
+-----
+
+===== Links specifying link text
+
+If you don't specify link text, the URL is used as the link text.
+
+
+*Examples*
+
+If you want your link to display as {logstash-ref}/getting-started-with-logstash.html, use this format:
+[source,txt]
+-----
+{logstash-ref}/getting-started-with-logstash.html
+-----
+
+
+If you want your link to display as {logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash], use this format:
+[source,txt]
+-----
+{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]
+-----
+
+
+===== Link to data type descriptions
+
+We make an exception for links that point to data type descriptions,
+such as `<<boolean,boolean>>`, because they are used so frequently. 
+We have a cleanup step in the conversion script that converts the links to the
+correct syntax. 
+
 
 [[format-code]]
 ==== Code samples
@@ -41,23 +114,23 @@ a duplicate, and the build will fail.
 We all love code samples. Asciidoc supports code blocks and config examples.
 To include Ruby code, use the asciidoc `[source,ruby]` directive.
 
-Note that the hash marks (#) are present to make the example render correctly.
+Note that the hashmarks (#) are present to make the example render correctly.
-Don't include the hash marks in your asciidoc file.
+Don't include the hashmarks in your asciidoc file.
 
 [source,txt]
 [subs="attributes"]
 ----------------------------------
 # [source,ruby]
-# ----------------------------------
+# -----
 # match => {
 #  "field1" => "value1"
 #  "field2" => "value2"
 #  ...
 # }
-# ----------------------------------
+# -----
 ----------------------------------
 
-This sample renders in the documentation like this:
+The sample above (with hashmarks removed) renders in the documentation like this:
 [source,ruby]
 ----------------------------------
 match => {
@@ -67,10 +140,43 @@ match => {
 }
 ----------------------------------
 
+==== Where's my doc?
+
+Plugin documentation goes through several steps before it gets published in the 
+{lsplugindocs}[Logstash Versioned Plugin Reference] and the {logstash-ref}/index.html[Logstash Reference].
+
+Here's an overview of the workflow:
+
+* Be sure that you have signed the CLI and have all necessary approvals and sign offs.
+* Merge the pull request for your plugin (including the `index.asciidoc` file, the `changelog.md` file, and the gemspec).
+* Wait for the continuous integration build to complete successfully.
+* Publish the plugin to https://rubygems.org.
+* A script detects the new or changed version, and picks up the `index.asciidoc` file for inclusion in the doc build.
+* The documentation for your new plugin is published in the {lsplugindocs}[Logstash Versioned Plugin Reference].
+
+We're not done yet. 
+
+* For each release, we package the new and changed documentation files into a pull request to add or update content.
+(We sometimes package plugin docs between releases if we make significant changes to plugin documentation or add a new plugin.)
+* The script detects the new or changed version, and picks up the `index.asciidoc` file for inclusion in the doc build.
+* We create a pull request, and merge the new and changed content into the appropriate version branches.
+* For a new plugin, we add a link to the list of plugins in the {logstash-ref}/index.html[Logstash Reference].
+* The documentation for your new (or changed) plugin is published in the {logstash-ref}/index.html[Logstash Reference].
+
+===== Documentation or plugin updates
+
+When you make updates to your plugin or the documentation, consider
+bumping the version number in the changelog and gemspec (or version file). The
+version change triggers the doc build to pick up your changes for publishing. 
 
 ==== Resources
 
 For more asciidoc formatting tips, see the excellent reference at
-https://github.com/elastic/docs#asciidoc-guide
+https://github.com/elastic/docs#asciidoc-guide.
 
+For tips on contributing and changelog guidelines, see
+https://github.com/elastic/logstash/blob/master/CONTRIBUTING.md#logstash-plugin-changelog-guidelines[CONTRIBUTING.md].
+
+For general information about contributing, see
+{logstash-ref}/contributing-to-logstash.html[Contributing to Logtash].
 

docs/static/include/pluginbody.asciidoc

@@ -13,7 +13,7 @@ https://www.ruby-lang.org/en/documentation/quickstart/[].)
 
 {getstarted}
 
-==== Create a GitHub repo for your new plugin
+===== Create a GitHub repo for your new plugin
 Each Logstash plugin lives in its own GitHub repository. To create a new repository for your plugin:
 
 . Log in to GitHub.
@@ -25,7 +25,7 @@ Each Logstash plugin lives in its own GitHub repository. To create a new reposit
 ** **Initialize this repository with a README** -- enables you to immediately clone the repository to your computer.
 . Click **Create Repository**.
 
-==== Use the plugin generator tool
+===== Use the plugin generator tool
 
 You can now create your own Logstash plugin in seconds! The `generate` subcommand of `bin/logstash-plugin` creates the foundation 
 for a new Logstash plugin with templatized files. It creates the correct directory structure, gemspec files, and dependencies so you 
@@ -33,7 +33,7 @@ can start adding custom code to process data with Logstash.
 
 For more information, see <<plugin-generator>>
 
-==== Copy the {plugintype} code
+===== Copy the {plugintype} code
 
 Alternatively, you can use the examples repo we host on github.com
 
@@ -92,7 +92,7 @@ For more information about the Ruby gem file structure and an excellent
 walkthrough of the Ruby gem creation process, see
 http://timelessrepo.com/making-ruby-gems
 
-==== See what your plugin looks like
+===== See what your plugin looks like
 
 Before we dive into the details, open up the plugin file in your favorite text editor
 and take a look.
@@ -312,7 +312,7 @@ endif::multi_receive_method[]
 
 Now let's take a line-by-line look at the example plugin.
 
-==== `encoding`
+===== `encoding`
 
 It seems like a small thing, but remember to specify the encoding at the
 beginning of your plugin code:
@@ -325,7 +325,7 @@ beginning of your plugin code:
 Logstash depends on things being in UTF-8, so we put this here to tell the Ruby
 interpreter that we’re going to be using the UTF-8 encoding.
 
-==== `require` Statements
+===== `require` Statements
 
 Logstash {plugintype} plugins require parent classes defined in
 +logstash/pass:attributes[{plugintype}]s/base+ and logstash/namespace:
@@ -344,16 +344,7 @@ them here along with these Logstash dependencies.
 
 Let's go through the various elements of the plugin itself.
 
-==== Documentation for your plugin
+===== `class` Declaration
-Documentation is an important part of your plugin. All plugin documentation is
-rendered and placed in the 
-http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash
-Reference] and the {lsplugindocs}[Versioned plugin docs].
-
-See <<plugin-doc>> for tips and guidelines.
-
-
-==== `class` Declaration
 The {plugintype} plugin class should be a subclass of
 +LogStash::pass:attributes[{pluginclass}]::Base+:
 
@@ -370,7 +361,7 @@ The class name should closely mirror the plugin name, for example:
 LogStash::{pluginclass}::{pluginnamecap}
 ----
 
-==== `config_name`
+===== `config_name`
 [source,ruby]
 [subs="attributes"]
 ----------------------------------
@@ -455,7 +446,7 @@ will become a valid boolean in the config.  This coercion works for the
 // /////////////////////////////////////////////////////////////////////////////
 ifdef::register_method[]
 
-==== `register` Method
+===== `register` Method
 [source,ruby]
 [subs="attributes"]
 ----------------------------------
@@ -484,7 +475,7 @@ endif::register_method[]
 ifdef::filter_method[]
 ifndef::blockfilter[]
 
-==== `filter` Method
+===== `filter` Method
 
 [source,ruby]
 [subs="attributes"]
@@ -539,7 +530,7 @@ endif::filter_method[]
 ifdef::decode_method[]
 ifndef::blockcodec[]
 
-==== `decode` Method
+===== `decode` Method
 
 [source,ruby]
 [subs="attributes"]
@@ -569,7 +560,7 @@ endif::decode_method[]
 ifdef::encode_method[]
 ifndef::blockcodec[]
 
-==== `encode` Method
+===== `encode` Method
 
 [source,ruby]
 [subs="attributes"]
@@ -596,7 +587,7 @@ endif::encode_method[]
 ifdef::run_method[]
 ifndef::blockinput[]
 
-==== `run` Method
+===== `run` Method
 
 The {pluginname} input plugin has the following `run` Method:
 
@@ -684,7 +675,7 @@ endif::run_method[]
 // /////////////////////////////////////////////////////////////////////////////
 ifdef::receive_method[]
 
-==== `receive` Method
+===== `receive` Method
 
 [source,ruby]
 [subs="attributes"]
@@ -747,9 +738,9 @@ endif::receive_method[]
 ==== Building the Plugin
 
 At this point in the process you have coded your plugin and are ready to build
-a Ruby Gem from it.  The following steps will help you complete the process.
+a Ruby Gem from it. The following information will help you complete the process.
 
-==== External dependencies
+===== External dependencies
 
 A `require` statement in Ruby is used to include necessary code. In some cases
 your plugin may require additional files.  For example, the collectd plugin
@@ -788,7 +779,7 @@ will be discussed further in the testing section of this document.
 Another kind of external dependency is on jar files.  This will be described
 in the "Add a `gemspec` file" section.
 
-==== Add a Gemfile
+===== Add a Gemfile
 
 Gemfiles allow Ruby's Bundler to maintain the dependencies for your plugin.
 Currently, all we'll need is the Logstash gem, for testing, but if you require
@@ -854,7 +845,7 @@ please make sure to have this line in your gemspec:
 The gem version, designated by `s.version`, helps track changes to plugins over
 time. You should use http://semver.org/[semver versioning] strategy for version numbers. 
 
-==== Runtime & Development Dependencies
+===== Runtime and Development Dependencies
 
 At the bottom of the `gemspec` file is a section with a comment:
 `Gem dependencies`.  This is where any other needed gems must be mentioned. If
@@ -881,7 +872,7 @@ it have a version number greater than or equal to version 1.60 and less than or
 IMPORTANT: All plugins have a runtime dependency on the `logstash-core-plugin-api` gem, and
 a development dependency on `logstash-devutils`.
 
-==== Jar dependencies
+===== Jar dependencies
 
 In some cases, such as the
 https://github.com/logstash-plugins/logstash-output-elasticsearch/blob/master/logstash-output-elasticsearch.gemspec#L22-L23[Elasticsearch output plugin],
@@ -899,6 +890,16 @@ added in the gemspec file in this manner:
 With these both defined, the install process will search for the required jar
 file at http://mvnrepository.com and download the specified version.
 
+
+==== Document your plugin
+Documentation is an important part of your plugin. All plugin documentation is
+rendered and placed in the 
+http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash
+Reference] and the {lsplugindocs}[Versioned plugin docs].
+
+See <<plugin-doc>> for tips and guidelines.
+
+
 ==== Add Tests
 
 Logstash loves tests. Lots of tests. If you're using your new {plugintype}
@@ -960,7 +961,7 @@ Hooray! You're almost there! (Unless you saw failures... you should fix those
 
 Now you're ready to build your (well-tested) plugin into a Ruby gem.
 
-==== Build
+===== Build
 You already have all the necessary ingredients, so let's go ahead and run the
 build command:
 
@@ -979,7 +980,7 @@ logstash-{plugintype}-mypluginname-0.1.0.gem
 The `s.version` number from your gemspec file will provide the gem version, in
 this case, `0.1.0`.
 
-==== Test installation
+===== Test installation
 
 You should test install your plugin into a clean installation of Logstash.
 Download the latest version from the
@@ -1166,7 +1167,7 @@ Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin
 artifacts. Once you have developed your new plugin, you can make it available to
 Logstash users by simply publishing it to RubyGems.org.
 
-==== Licensing
+===== Licensing
 Logstash and all its plugins are licensed under
 https://github.com/elasticsearch/logstash/blob/master/LICENSE[Apache License, version 2 ("ALv2")].
 If you make your plugin publicly available via http://rubygems.org[RubyGems.org],
@@ -1174,7 +1175,7 @@ please make sure to have this line in your gemspec:
 
 * `s.licenses = ['Apache License (2.0)']`
 
-==== Publishing to http://rubygems.org[RubyGems.org]
+===== Publishing to http://rubygems.org[RubyGems.org]
 
 To begin, you’ll need an account on RubyGems.org
 
@@ -1235,7 +1236,7 @@ It is not required to contribute your source code to
 https://github.com/logstash-plugins[logstash-plugins] github organization, but
 we always welcome new plugins!
 
-==== Benefits
+===== Benefits
 
 Some of the many benefits of having your plugin in the logstash-plugins
 repository are:
@@ -1249,11 +1250,11 @@ tested against current and future releases of Logstash.  As a result, users will
 have the assurance that if incompatibilities arise, they will be quickly
 discovered and corrected.
 
-==== Acceptance Guidelines
+===== Acceptance Guidelines
 
-* **Code Review** Your plugin must be reviewed by members of the community for
+* **Code Review.** Your plugin must be reviewed by members of the community for
 coherence, quality, readability, stability and security.
-* **Tests** Your plugin must contain tests to be accepted.  These tests are also
+* **Tests.** Your plugin must contain tests to be accepted.  These tests are also
 subject to code review for scope and completeness.  It's ok if you don't know
 how to write tests -- we will guide you. We are working on publishing a guide to
 creating tests for Logstash which will make it easier.  In the meantime, you can