[synthetics] Incorporate lightweight monitors more thoroughly into docs

[colleenmcginnis]

⚠️ Note: This is a work in progress.

Background

@andrewvc @lucasfcosta and I met a couple weeks ago to discuss synthetics docs issues. One issue that came up was incorporating more lightweight monitor content throughout the docs.

Overview

This PR proposes to:

• Continue to keep browser-specific content separate from lightweight monitor content because users have to learn significantly more concepts to implement browser monitors. We should make it easy to implement lightweight monitors without sifting through content that is only relevant to browser monitors.
• Reframes existing titles of browser-specific content like "Use synthetic monitors" to be more specific: "Use browser monitors".
• Adds a "Use lightweight monitors" page that can act as an equivalent to "Use browser monitors". Note: I'm not sure what level of detail to include here yet.

To do

• @andrewvc @lucasfcosta @colleenmcginnis align on the approach 👈 we are here!
• @colleenmcginnis write, refine text
• @andrewvc @lucasfcosta review complete draft
• @colleenmcginnis clean up for publication
  • address feedback
  • lint content

[apmmachine]

A documentation preview will be available soon:

• 📚 HTML diff
• 📘 Fleet and Elastic Agent Guide
• 📙 Observability Guide

[lucasfcosta]

I'm okay with having this page, I just didn't fully understand what you wish to include in each section.

IMO we could also break that page down into multiple sub-pages to cover the specific options for each type of monitor. IMO that would make it easier for users to find the information they want.

It's also worth noticing that although you updated the "browser" titles here, the overall section title in the docs is still "uptime and synthetic monitoring", so I think we should change it there as well to be consistent.

[lucasfcosta]

IMO the main difference between these and browser monitors is that there isn't a browser environment that needs to be spun-up. Therefore, these are usually quicker.

[lucasfcosta]

I think there will be plenty of common options for us to list together, so perhaps we could start with the "common required options", then move on to the options that are specific for each monitor, and then list "common options" (the remaining non-required ones).

[lucasfcosta]

Isn't this section a bit redundant considering the previous "configure a monitor" section?

[colleenmcginnis]

Apologies -- meant to be the lightweight equivalent of Create a browser monitor, but if there's not enough to say specifically for lightweight monitors (like there is for browser monitors) then we can remove it.

[lucasfcosta]

Not sure I understand what you mean by manage. Is it editing and deleting them? Or is it managing the results (i.e. viewing results and debugging)?

[colleenmcginnis]

Meant to be the lightweight equivalent of Manage browser monitors, but if there's not enough to say specifically for lightweight monitors (like there is for browser monitors) then we can remove it.

[colleenmcginnis]

IMO we could also break that page down into multiple sub-pages to cover the specific options for each type of monitor. IMO that would make it easier for users to find the information they want.

Ok. I'll give this a try and we can see what it looks like!

It's also worth noticing that although you updated the "browser" titles here, the overall section title in the docs is still "uptime and synthetic monitoring", so I think we should change it there as well to be consistent.

"Uptime and synthetic monitoring" attempts to signal to readers that this section contains information about the "Uptime" UI in Kibana, but also the industry term "synthetic monitors". 🤷‍♀️ Do you think that is still important?

[lucasfcosta]

"Uptime and synthetic monitoring" attempts to signal to readers that this section contains information about the "Uptime" UI in Kibana, but also the industry term "synthetic monitors". 🤷‍♀️ Do you think that is still important?

@colleenmcginnis that's a good question. I think just changing "synthetic monitors" to maybe "synthetic monitoring" could help as that names the practice rather than the type of monitors ("browser monitors"), but in that case I wonder whether the change is even worth doing given it's so small. I don't think anyone would notice in that case tbh.

In any case, I'm not strongly opinionated about that.

[colleenmcginnis]

Note: I'm going to hold on this until #2075 is finalized. (I didn't anticipate that other PR impacting the changes here initially, but the changes overlap.)

[mergify]

This pull request is now in conflict. Could you fix it @colleenmcginnis? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b uptime-vocab upstream/uptime-vocab
git merge upstream/main
git push upstream uptime-vocab

[colleenmcginnis]

Closing in favor of #2372 and #2353