[apm] Update APM section information architecture

[colleenmcginnis]

Closes https://github.com/elastic/obs-docs-projects/issues/260
Closes #817

Updates the information architecture of the APM section.

Preview: https://observability-docs_bk_4230.docs-preview.app.elstc.co/guide/en/observability/master/apm.html

Approach

User-facing changes:

• Better integrate APM UI content with existing APM content. Recently we moved APM UI content from the Kibana guide to the Observability guide (Move APM UI documentation to observability-docs with history #3723). At the time we just lifted and shifted the content. This PR attempts to better integrate that content with existing APM content in the Observability guide.
• Organizes content (roughly) chronologically. The subsections under APM are organized in roughly the order of the phases a user may go through – getting started, sending data to Elastic, viewing and interpreting that data, fine-tuning their implementation, and then upgrading when a new release comes out.

• Eliminate unintuitive subsection titles. For example, the "Features” subsection.

Contributor-related changes:

• Consistifies how pages are included. Aims to establishes a consistent pattern for page-to-file relationships, headings/leveloffsets, and includes:
  • One file should map to each page.
  • Every file should start with heading level 1. (Need to confirm this works as expected in the preview build -- it does work locally.)
  • Pages that are nested under a section in the table of contents are included at the bottom of the file associated with the parent page.
• Consistently uses subdirectories. Instead of sometimes using subdirectories and sometimes using a flat directory section, it always uses a subdirectory within the apm directory.

New content

I wrote some new content on new “landing” pages for subsections within the APM section. These need closer review.

Goals

I had a few goals with these pages:

• Tell a story. The first level under “Application performance monitoring (APM)” should tell the full, yet high-level, story of a user’s experience with APM with a beginning, a middle, and an end.
• Establish context in each subsection. Some subsections are used to group together alternatives (pick this or that), while others are used to group together related tasks/concepts.
  • In the former, the landing page should aim to assist in decision making – the user should be able to compare/contrast alternatives at a high level to reduce the need to read through the whole doc for each alternative.
  • In the latter, some subsections have pages with content that builds throughout the subsection, while others are plain old siblings that can be read in any order. The landing page for each subsection establishes the relationship between its children pages.
  • Note: We know users usually don’t read docs from the top of the toc to the bottom in order. Instead the intent is to establish the context in case a user lands on a page from search results, and is not sure the page is right for them – they have the option of backing up to see some context.

Pages to be reviewed

Here are the pages with new content that need review:

• Data model
  Describes the relationship between event types in both the text and a diagram.
• Collect application data
  Presents alternative methods for collecting data and helps the user decide which page(s) might be relevant to them to streamline their experience.
  • APM agents
    Lists available agents and links to the docs. Mentions that for the most part, they should get information from the agent docs, but there are a couple resources in the Observability guide with content that applies to multiple agents and/or the APM UI.
• View and analyze data
  Establishes that they might want to progress through this content in order as they get more familiar with the APM UI.
  • Filter and search
    Establishes why this is important.
  • Interpret data
• Act on data
• Use APM securely
• APM APIs

Review checklist

Rough checklist for now!

• Initial draft
• Get answers and clean up all TO DOs
• Review the overall structure of the APM section
• Review new content (see "Pages to be reviewed" above)
• Implement and verify redirects (Google sheet)

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[colleenmcginnis]

FYI @bmorelli25 if you see strange heading behavior, it should be addressed in elastic/docs#3060.

[bmorelli25]

great work on this, @colleenmcginnis

@elastic/obs-ds-intake-services we need to merge this PR as it's becoming too time consuming to continue to fix merge conflicts as other changes in these files merge into main.

[lahsivjar]

Gave a brief reading, just a few minor comments. LGTM! Thanks for doing this!

[lahsivjar]

LGTM!

[bmorelli25]

LGTM !!