Fix over-linking issues in web exporter documentation

Jon Glassmanrequested to merge
fix-web-exporter-overlinking into master

What does this MR do and why?

This MR addresses over-linking issues in the web exporter documentation that were disrupting reading flow and violating GitLab documentation standards.

Problems identified:

  • Flow-disrupting parenthetical links: Mid-sentence links that break reading flow
  • Overwhelming procedural links: Nearly every task step contained multiple links
  • Multiple links per sentence: Complex sentences with multiple concepts linked

Changes made:

🔴 High Priority Fixes:

  1. Removed flow-disrupting parenthetical links:

    • Removed inline Puma link that was explanatory but not essential
    • Removed mid-sentence Docker links that interrupted reading flow

  2. Consolidated procedural links into "Related topics" sections:

    • Moved Prometheus configuration links out of task steps
    • Created dedicated "Related topics" sections after major procedures
    • Kept only essential reconfigure GitLab link in task steps

  3. Simplified task steps:

    • Step 1: Removed link to "Enable Prometheus" (should be prerequisite knowledge)
    • Step 3: Removed three inline links, moved to Related topics
    • Troubleshooting: Moved Docker links to Related topics section

🟡 Medium Priority Fixes:

  1. Restructured multiple links per sentence:
    • Simplified complex sentences in the "How GitLab metrics collection works" section
    • Broke down explanatory text to reduce cognitive load

Impact:

  • Link density reduced from 6/10 to approximately 3/10
  • Improved task flow: Users can complete procedures without link distractions
  • Better readability: Cleaner sentences with fewer interruptions
  • Maintained navigation: All important links preserved in Related topics sections

Compliance with GitLab standards:

  • ✅ Follows guideline to "avoid multiple links in a single task"
  • ✅ Reduces cognitive load as recommended in style guide
  • ✅ Uses "Related topics" pattern for supplementary information
  • ✅ Maintains descriptive link text standards
  • ✅ Preserves all necessary navigation paths

Screenshots or screen recordings

Before:

  • Task steps contained 3+ links each
  • Mid-sentence parenthetical links disrupted flow
  • Complex sentences with multiple linked concepts

After:

  • Clean task steps focused on actions
  • Links organized in Related topics sections
  • Simplified explanatory text

How to set up and validate locally

  1. Review the updated documentation at doc/administration/monitoring/prometheus/web_exporter.md
  2. Verify that:
    • Task procedures are easier to follow
    • Related topics sections provide necessary navigation
    • Reading flow is improved without losing essential information

MR acceptance checklist

  • Code review guidelines
  • Merge request performance guidelines
  • Style guides
  • Database guidelines
  • Separation of EE specific content

Merge request reports