Doc: SNMP integration: Manage messaging and set user expections during rollout

[karenzone]

SNMP integration plugin

The new integration-snmp plugin has absorbed input-snmp and input-snnptrap plugins at v4.0.0.
The stand-alone input-snmp and input-snnptrap plugins are bundled by default, and we'll need to clearly communicate expectations for our users for Technical Preview and beyond.

IMPORTANT: Clearly communicate what users should expect when the snmp integration goes GA, and is bundled by default. (Mapping changes, preserving existing behavior, etc.) For example, will the stand-alone inputs be uninstalled and replaced by the integration and its inputs when it is bundled? What is the target release?

Current doc status

• Integration-snmp 4.0.0 landing page is LIVE in the Versioned Plugin Reference (VPR). 🎉
  Note that cross-doc links are disabled because targets aren't yet in place.
• LSR build implementation pending (because users still need existing docs for standa-alone input-snmp and input-snmptrap while the integration is in Technical Preview).
  I have a very basic placeholder up for testing and validation: https://www.elastic.co/guide/en/logstash/master/plugins-integrations-snmp.html.

Proposal

• Put manually created placeholders in place to reflect appropriate messaging for each Logstash branch.
• Those placeholders should remain in place until we start generating the docs for the snmp integration for appropriate branches.
  (Note that we might have manage files manually to prevent them from being overwritten as we release patch releases. OR, manually tweak the lockfile to prevent overwriting.)
• ACKNOWLEDGEMENT. Generally, we want plugin docs to be generated from source docs in the repo, and manual adjustment is a "no no". Having default stand-alone plugins absorbed into an integration in Tech Preview is an usual situation., and this might be the best approach.

To Do

• Craft appropriate messaging for each branch (main, 8.15, 8.14, and 8.13)
• What are the implications for 7.17?
• Breaking changes implications for release notes? (Mapping differences, etc.)
• Manage lockfile to patch releases to prevent placeholder docs from being overwritten prematurely.

Limitations in the interim

• Without all files in place, cross-doc linking will be limited. For example, snmp pages in the Versioned Plugin Reference won't be able to deep link into other SNMP pages in the Logstash Reference until those pages are in place. Hard-coded test may look like errors.

Fixes

• Doc: Introduce snmp-integration for Technical Preview logstash-docs#1648
• Doc: Introduce snmp-integration for Technical Preview 8.14 logstash-docs#1652
• Doc: Introduce snmp-integration for Technical Preview 8.13 logstash-docs#1653

[karenzone]

@jsvd, here's my proposal to move this forward:

• Adjust messaging as needed for Doc: Introduce snmp-integration for Technical Preview logstash-docs#1648.
• Merge the placeholder file for main and 7.14 branches.
• Merge Update plugins-metadata.json with integration-snmp: set skiplist to false #16137 to enable docgen to pick up snmp-integration for the Logstash Reference.
  • If all goes well, the integration-snmp landing page will be updated for master.
  • Ideally, we'd leave the manually generated landing page in place to maintain appropriate messaging for the 8.14 branch.