docs(outputs): Clean up, reorder (#15358)

docs/OUTPUTS.md

@@ -16,12 +16,81 @@ similar constructs.
 - Each plugin requires a file called `sample.conf` containing the sample
   configuration  for the plugin in TOML format.
   Please consult the [Sample Config][] page for the latest style guidelines.
-- Each plugin `README.md` file should include the `sample.conf` file in a section
+- Each plugin `README.md` file should include the `sample.conf` file in a
-  describing the configuration by specifying a `toml` section in the form `toml @sample.conf`. The specified file(s) are then injected automatically into the Readme.
+  section describing the configuration by specifying a `toml` section in the
+  form `toml @sample.conf`. The specified file(s) are then injected
+  automatically into the Readme.
 - Follow the recommended [Code Style][].
 
+[Sample Config]: /docs/developers/SAMPLE_CONFIG.md
+[Code Style]: /docs/developers/CODE_STYLE.md
+[telegraf.Output]: https://godoc.org/github.com/influxdata/telegraf#Output
+
+## Data Formats
+
+Some output plugins, such as the [file][] plugin, can write in any supported
+[output data formats][].
+
+In order to enable this, you must specify a
+`SetSerializer(serializer serializers.Serializer)`
+function on the plugin object (see the file plugin for an example), as well as
+defining `serializer` as a field of the object.
+
+You can then utilize the serializer internally in your plugin, serializing data
+before it's written. Telegraf's configuration layer will take care of
+instantiating and creating the `Serializer` object.
+
+You should also add the following to your `SampleConfig()`:
+
+```toml
+  ## Data format to output.
+  ## Each data format has its own unique set of configuration options, read
+  ## more about them here:
+  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
+  data_format = "influx"
+```
+
+[file]: /plugins/inputs/file
+[output data formats]: /docs/DATA_FORMATS_OUTPUT.md
+
+## Flushing Metrics to Outputs
+
+Metrics are flushed to outputs when any of the following events happen:
+
+- `flush_interval + rand(flush_jitter)` has elapsed since start or the last
+  flush interval
+- At least `metric_batch_size` count of metrics are waiting in the buffer
+- The telegraf process has received a SIGUSR1 signal
+
+Note that if the flush takes longer than the `agent.interval` to write the
+metrics to the output, user will see a message saying the output:
+
+> did not complete within its flush interval
+
+This may mean the output is not keeping up with the flow of metrics, and you may
+want to look into enabling compression, reducing the size of your metrics or
+investigate other reasons why the writes might be taking longer than expected.
+
 ## Output Plugin Example
 
+## Registration
+
+Registration of the plugin on `plugins/outputs/all/simpleoutput.go`:
+
+```go
+//go:build !custom || outputs || outputs.simpleoutput
+
+package all
+
+import _ "github.com/influxdata/telegraf/plugins/outputs/simpleoutput" // register plugin
+
+```
+
+The _build-tags_ in the first line allow to selectively include/exclude your
+plugin when customizing Telegraf.
+
+## Plugin
+
 Content of your plugin file e.g. `simpleoutput.go`
 
 ```go
@@ -79,61 +148,3 @@ func init() {
     outputs.Add("simpleoutput", func() telegraf.Output { return &Simple{} })
 }
 ```
-
-Registration of the plugin on `plugins/outputs/all/simpleoutput.go`:
-
-```go
-//go:build !custom || outputs || outputs.simpleoutput
-
-package all
-
-import _ "github.com/influxdata/telegraf/plugins/outputs/simpleoutput" // register plugin
-
-```
-
-The _build-tags_ in the first line allow to selectively include/exclude your
-plugin when customizing Telegraf.
-
-## Data Formats
-
-Some output plugins, such as the [file][] plugin, can write in any supported
-[output data formats][].
-
-In order to enable this, you must specify a
-`SetSerializer(serializer serializers.Serializer)`
-function on the plugin object (see the file plugin for an example), as well as
-defining `serializer` as a field of the object.
-
-You can then utilize the serializer internally in your plugin, serializing data
-before it's written. Telegraf's configuration layer will take care of
-instantiating and creating the `Serializer` object.
-
-You should also add the following to your `SampleConfig()`:
-
-```toml
-  ## Data format to output.
-  ## Each data format has its own unique set of configuration options, read
-  ## more about them here:
-  ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
-  data_format = "influx"
-```
-
-## Flushing Metrics to Outputs
-
-Metrics are flushed to outputs when any of the following events happen:
-
-- `flush_interval + rand(flush_jitter)` has elapsed since start or the last flush interval
-- At least `metric_batch_size` count of metrics are waiting in the buffer
-- The telegraf process has received a SIGUSR1 signal
-
-Note that if the flush takes longer than the `agent.interval` to write the metrics
-to the output, you'll see a message saying the output `did not complete within its
-flush interval`. This may mean your output is not keeping up with the flow of metrics,
-and you may want to look into enabling compression, reducing the size of your metrics,
-or investigate other reasons why the writes might be taking longer than expected.
-
-[file]: https://github.com/influxdata/telegraf/tree/master/plugins/inputs/file
-[output data formats]: https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md
-[Sample Config]: https://github.com/influxdata/telegraf/blob/master/docs/developers/SAMPLE_CONFIG.md
-[Code Style]: https://github.com/influxdata/telegraf/blob/master/docs/developers/CODE_STYLE.md
-[telegraf.Output]: https://godoc.org/github.com/influxdata/telegraf#Output