[DOCS] Clarify changes in monitoring settings

[dedemorton]

Closes #13994

Marking as WIP because I want to verify that the general structure/approach works before proceeding.

I plan to backport this to 7.2 to clarify the messaging.

@ycombinator Can you take a look and see if I'm on the right track. Note that I took the "legacy" settings from 7.1. Let me know if that's not the right approach (I'm assuming they were not changed between 7.1 and 7.2).

[ycombinator]

Will do on Monday, @dedemorton! Is this the right preview URL? http://beats_15003.docs-preview.app.elstc.co/guide/en/beats/auditbeat/master/monitoring.html

[dedemorton]

@ycombinator Yup, that preview link will work!

[ycombinator]

I'm a little torn about the ordering of the collection methods presented in this PR. I wonder if it should be Internal collection*, Metricbeat collection, then Legacy collection* (deprecated) instead.

I say this because, in 7.x we're going to want users to use the Internal collection method for sure to ease their upgrade pain. In 8.0/8.x we'd want to do the same until Agent becomes available. In short, while Metricbeat collection is an option for users, I don't think we want to emphasize it too much for monitoring other Beats. @cachedout @jakelandis @ph do you have any opinions here as well, based on our recent discussions?

*See my other comment in the PR about the naming of "Internal collection" and "Legacy collection".

[dedemorton]

I think this terminology might be confusing, since we use "Internal collection" for other products to mean "internal collection sending data to the production cluster" (what you're calling "legacy collection" below).

Agreed...do you think it would be better if I called them: "internal collection" and "internal collection (legacy)" (so it's clear that they're both basically internal collection, but the one flagged "legacy" is old and deprecated)?

[dedemorton]

I tried a version where I spelled things out in the title (Internal collection - sending to the production cluster and Internal collection - sending directly to the monitoring cluster), but I was concerned that users who don't have a dedicated monitoring cluster might think the first topic applied to them. Also long titles can be problematic.

[ycombinator]

Perhaps the solution here is to call them "internal collection" and "internal collection (legacy)" but to also update other products' docs to use the "internal collection (legacy)" title?

[dedemorton]

@karenzone WDYT about the naming that I've proposed here? I'm open to better ideas!

[karenzone]

All good points in the previous discussions.

What about "internal collection," and "legacy internal collection (deprecated)." If you use internal collection (legacy), that sets you up for back-to-back parentheticals when you add (deprecated).

[karenzone]

LGTM

[ycombinator]

@dedemorton Post-holiday bump :)

[dedemorton]

Post-holiday bump :)

Hey who took away the eggnog?

[ycombinator]

@dedemorton Looks like this needs a rebase with master to update the NOTICE.txt file with the new year.

[dedemorton]

@ycombinator I've rebased. Is this ready to merge?

[ycombinator]

Left a nit comment. Otherwise LGTM. Thanks @dedemorton!