[Internal]: Update Asset Discovery Integrations docs

[uri-weisman]

Description

Few fixes/improvents that we want to apply to the asset discovery integration docs:

Reset filters section has a link that takes users to Elastic Security Overview doc page. This page is too generic and does not offer any in-depth information about how Asset Inventory or the Cloud Asset Discovery integration works.

In elastic.co/docs/, if you search for "Asset Inventory" you find 2 "Cloud Asset Discovery" pages, but there are no links in-between:

• Cloud Asset Discovery integration, whose slug is the outdated cloud-asset-inventory and reference index is the outdated Cloud Asset Integration
• Cloud Asset Discovery integration, whose slug is asset-dics and describes how to install it with the 3 main cloud platforms

3. Incorrect cross-page anchors for “Agentless” / “Agent-based”. Those anchor links in GCP and AWS pages incorrectly link to anchors in Azure page (asset-disc-azure#cad-azure-agentless / #cad-azure-agent-based)
4. Passing the 3 pages to an LLM quickly finds lots of inconsistencies and ways to standardize our documentation writing style. We should make sure we introduce AI to the documentation process.

Table with small inconsistencies

Table that checks similar content presence and potential patterns to follow

Resources

No need features introduced.

Which documentation set does this change impact?

Elastic On-Prem and Cloud (all)

Feature differences

Already captured in docs.

What release is this request related to?

9.2

Serverless release

irrelevant

Collaboration model

The documentation team

Point of contact.

Main contact: @elastic/core-analysis (@uri-weisman )

Stakeholders: @caitlinbetz

[alaudazzi]

I connected with @uri-weisman through Slack to clarify the doc fixes requested in this ticket.
Also, I removed the 9.2 label based on the fact that "It would be nice, but it’s definitely not a must; there’s nothing new here besides fixes."

[alaudazzi]

Actions identified after sync with Uri:

• 1. On the reference page Cloud Asset Discovery, fix the link that should point to the getting started, but actually takes you to the Cloud security page.
• 2. Consider consolidating these two pages:
  • https://www.elastic.co/docs/solutions/security/cloud/asset-disc
  • https://www.elastic.co/docs/reference/integrations/cloud_asset_inventory
    => Addressed in this comment.
• 3. On the page https://www.elastic.co/docs/reference/integrations/cloud_asset_inventory, change the slug from inventory to discovery
  => Addressed in this comment.
• 4. Fix anchors:
  Incorrect cross-page anchors for “Agentless” / “Agent-based”. Those anchor links in GCP and AWS pages incorrectly link to anchors in Azure page (asset-disc-azure#cad-azure-agentless / #cad-azure-agent-based).
  For example, if you navigate to https://www.elastic.co/docs/solutions/security/cloud/asset-disc-aws#cad-azure-agentless you end up in Set up Cloud Asset Discovery for AWS
• 5. Apply the new guidelines to the Cloud Asset Discovery Integration page.

[alaudazzi]

@benironside
I pushed this PR to fix steps 1 and 5. Can you have a look?

[alaudazzi]

For step 3, the navigation tree still displays the old name of the integration

Cloud Asset Discovery is the correct name.
This fix impacts the package naming in the integrations repo, which is something that cannot be fixed by a writer, I guess. @elastic/cloud-security-posture is the codeowner for the cloud_asset_inventory package.
It's on the cloud-security-posture team's radar.
"the issue is that the integration is still named cloud_asset_inventory in the integration repo, and most likely it’s an auto-generated list based on this data. Can raise it with the team, but it won’t be fixed before 9.2"

[alaudazzi]

Discussed step 2 with the security writers: The consolidation of content between solutions docs and reference docs is an opportunity that definitely goes beyond these two pages (https://www.elastic.co/docs/solutions/security/cloud/asset-disc
and https://www.elastic.co/docs/reference/integrations/cloud_asset_inventory). As a quick fix, we can reference them and make sure their content is accurate.

[alaudazzi]

Tasks completed. Closing.