Improve EDOT troubleshooting documentation

[alexandra5000]

Introduction

The troubleshooting documentation for EDOT Collector and SDKs presents numerous issues that stem from their freshness and lack of cohesiveness.

Content issues

• Coverage of problems is uneven. Some common issues are not present.
• Explanations are often insufficient or incomplete. They might take knowledge for granted. Other times, they explain overly technical details.
• Most documents mix general and specific troubleshooting approaches.
• Similar troubleshooting content is not being reused across documents. Some solutions and troubleshooting steps are common between SDKs.

Structural issues

• All troubleshooting information is stored together in a single topic for each distro.
• Each troubleshooting has a different structure. This makes comparison harder.
• The documentation is not living under the Troubleshooting section of the docs. It’s presented together with the Reference documentation.

Improving troubleshooting documentation can have a direct impact on user adoption, customer satisfaction, and retention of customers.

Suggested action plan

Phase 1: Gather data

• Check upstream docs for structure, common topics per area, depth of coverage, placement.
• Reach out to customer support to inform about the project and gather most common issues and inquiries from customers regarding EDOT. Do the same with PMs and Sales.
• Find out what the state of the art for troubleshooting docs currently is in the new IA. There might be none, so we can lead the way here.
• Present results to stakeholders.

Phase 2: Plan the actions

• Draft a proposal for topics restructuring and execution plan. It should describe:
  • New topics and planned updates.
  • Content lifecycle: how to update and maintain content.
  • Feedback mechanisms: how to collect feedback from stakeholders.
• Reach out to each distribution team to collect and validate proposed structure and topics.

Phase 3: Execution

• Organize new troubleshooting documentation in separate troubleshooting topics.
• Use the existing assembler mechanism to move the documentation to Troubleshooting.
• Consider contributing some of the troubleshooting documentation to upstream.

To be documented, as proposed by Luca:

• How to set --log-level=debug in containerized environments
• Explain or expand Verify Pipelines: Use otelctl diagnose (if available) to check pipeline health.
• Explain how to leverage the debug exporter to dump signals to file in debug for investigation
• Create a "what to provide/collect for a bug/issue" page/section