Reorder docs

[jalvz]

The docs are more or less structured like this (not all sections):

• Overview
  • Elasticsearch
  • Agents
  • Server
    • Overview
      • Why APM server is a separate component
    • Installing
    • Upgrading
    • Setting up and running
    • Configuring
      • Config file
      • High Availability
      • Dashboards
      • ...
    • Securing...
    • Event types
    • RUM
    • Tune data ingestion
    • Storage management
    • Intake API
    • Exploring data in Elasticsearch
    • Exported fields
    • Troubleshooting
    • Release notes
  • Kibana

Would be nice to have a more meaningful order based on:

• what information requires what (e.g. almost everything requires a user to know what is a transaction, so doc explaining transactions should go first)
• when is expected that a user will need a piece of documentation. Eg:
  • "RUM" is expected to be read very early, eg. when testing it in localhost.
  • "Securing" is expected to be read later, when deploying in prod.
  • reference-kind of docs (listings) are expected to be used much later, when after reading relevant sections, users don't find what they need.
  • internal details (like Intake API) are expected to be used by advance users that want to hack it, develop an agent, etc.

I suggest then to move some things to make it more like this:

• Overview
  • APM Data model (this is the "Event Types")
  • Elasticsearch
  • Agents
  • Server
    • Overview
      • Why APM server is a separate component
      • High Availability (moved from config to overview. this doc introduces the internal queue, which is referred to everywhere)
    • Installing
    • Setting up and running
    • RUM (moved up)
    • Securing...
    • Tune data ingestion
    • Storage management
    • Exploring data in Elasticsearch
    • Configuration (moved down)
    • Exported fields
    • Intake API (moved down)
    • Upgrading (moved down)
    • Troubleshooting
    • Release notes
  • Kibana

I think we can move the config section down because it is a wall of text with all config options. I hope that if the docs are any good, users should find the relevant settings for them in other sections (RUM, tune ingestion, etc.)

[jalvz]

@elastic/apm-server would like to not have this lying around for too long, should be easy to settle on something:

👍 / 👎 / 🤷‍♂️ ?

[jalvz]

@bmorelli25 fyi

[bmorelli25]

@jalvz I really like the idea of moving transactions and spans to the getting started documentation and renaming it to something like "APM Data Model" (like you show above)

With this change, we could also add a section on dropped and missing spans. This would allow the UI to link to this generic section, instead of to each individual agent's section.

[bmorelli25]

I'm playing around with a rework of the "Getting Started" and "Setting up and running" sections of the APM Server documentation.
Something like:

• Overview
• Getting Started With APM Server
  • Step 1: Install APM Server
  • Step 2: Configure APM Server
  • Step 3: Start APM Server
  • Step 4: Next steps
  • Repositories for APT and YUM
  • Running APM Server on Docker
• Setting up APM Server
  • Directory layout
  • Secrets keystore
  • Command reference
  • High Availability
  • APM Server and systemd
• Configuring
  • ...
• ...
• Troubleshooting
  • Common problems
  • Debug
  • Get help
• ...

A similar idea for the APM Overview: https://github.com/elastic/apm-server/compare/master%E2%80%A6bmorelli25:revamp-apm-overview

[jalvz]

@bmorelli25 you made several changes in this direction, so ill close this one. feel free to reopen if there is anything left you want to track