DOCS-1497 - Use Claude Code to replace image alt text that is “icon” or “thumbnail” with meaningful text

[jpipkin1]

Purpose of this pull request

This pull request replaces instances of alt text that are alt="icon" or alt="thumbnail icon" with meaningful text. I used Claude Code to assist with the task.

Select the type of change

• Minor Changes - Typos, formatting, slight revisions
• Update Content - Revisions, updating sections
• New Content - New features, sections, pages, tutorials
• Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

DOCS-1497

[jpipkin1]

Reviewer, to make the PR a little easier to review, I asked Claude Code to compile a list of the changes in this file: alt-text-complete-changes-table.md

You can view the file in Visual Studio Code in markdown preview mode:

The file will look like this:

[mafsumo]

Thanks for the comprehensive documentation! I've reviewed the alt text changes and found some issues that need correction. Out of 1,998 changes, approximately 36
entries (~1.8%) have problems. Here's the breakdown:

---

🚨 Critical Issues - Must Fix (6 entries)

1. Hash ID leaked into alt text

File: docs/alerts/webhook-connections/index.md

• ❌ Current: Now 6d5a01eb icon
• ✅ Should be: ServiceNow icon
• Issue: Contains hex hash 6d5a01eb from image filename

2. CSS class names leaked into alt text (2 instances)

File: docs/integrations/amazon-aws/api-gateway.md

• ❌ Current: Oojs Ui Icon External Link Ltr Progressive icon
• ✅ Should be: External link icon
• Issue: Technical UI class names from image source

File: docs/observability/aws/integrations/aws-api-gateway.md

• ❌ Current: Oojs Ui Icon External Link Ltr Progressive icon
• ✅ Should be: External link icon
• Issue: Same technical class name issue

3. Garbled/concatenated text (3 instances)

File: docs/apm/traces/advanced-configuration/correlate-logs.md

• ❌ Current: Javascript Logo Transparent Logo Javascript Images 3 icon
• ✅ Should be: JavaScript icon
• Issue: "Logo" repeated, includes "Transparent" and "Images 3" artifacts

File: docs/apm/traces/get-started-transaction-tracing/index.md (appears twice in this file)

• ❌ Current: Javascript Logo Transparent Logo Javascript Images 3 icon
• ✅ Should be: JavaScript icon
• Issue: Same concatenation problem

---

⚠️ Style/Consistency Issues - Should Fix

4. Incorrect title case - "And" should be lowercase (3 files, 12+ instances)

File: docs/alerts/monitors/index.md

• ❌ Current: Monitor And Visualize icon (appears 10 times)
• ✅ Should be: Monitor and Visualize icon

File: docs/api/muting-schedules.md

• ❌ Current: Monitor And Visualize icon (appears 2 times)
• ✅ Should be: Monitor and Visualize icon

File: docs/api/about-apis/getting-started.md

• ❌ Current: Security And Compliance icon
• ✅ Should be: Security and Compliance icon

File: docs/api/index.md

• ❌ Current: Security And Compliance icon
• ✅ Should be: Security and Compliance icon

File: docs/integrations/index.md

• ❌ Current: Scale And Elastic icon
• ✅ Should be: Scale and Elastic icon

5. "For" capitalization in product names (17 instances)

These need verification against official product naming. If these match official Azure/Microsoft branding, keep as-is. Otherwise, "for" should be lowercase:

Files with "For" capitalization:

• docs/integrations/amazon-aws/index.md
  • ❌ CIS For AWS icon → ✅ CIS for AWS icon (likely should be lowercase)

Azure product names (check official branding):

• docs/integrations/microsoft-azure/azure-cache-for-redis.md → Azure Cache For Redis icon
• docs/integrations/microsoft-azure/azure-cosmos-db-for-postgresql.md → Azure Cosmos DB For PostgreSQL icon
• docs/integrations/microsoft-azure/azure-database-for-mariadb.md → Azure Database For Mariadb icon
• docs/integrations/microsoft-azure/azure-database-for-mysql.md → Azure Database For MySQL icon
• docs/integrations/microsoft-azure/azure-database-for-postgresql.md → Azure Database For PostgreSQL icon
• docs/integrations/microsoft-azure/azure-security-defender-for-cloud.md → Microsoft Defender For Cloud icon
• docs/integrations/microsoft-azure/azure-security-microsoft-defender-for-cloud-apps.md → Azure Security Microsoft Defender For Cloud Apps icon
• docs/integrations/microsoft-azure/microsoft-defender-for-endpoint.md → Microsoft Defender For Identity icon

Plus 8 more instances in: docs/integrations/microsoft-azure/index.md

6. Brand name capitalization - ServiceNow (2 instances)

File: docs/alerts/webhook-connections/servicenow/set-up-connections.md

• ❌ Current: Create New Connection Servicenow icon
• ✅ Should be: Create New Connection ServiceNow icon
• ❌ Current: Create New Connection Servicenow Legacy
• ✅ Should be: Create New Connection ServiceNow Legacy

7. Brand name capitalization - MariaDB (1 instance)

File: docs/integrations/microsoft-azure/azure-database-for-mariadb.md

• ❌ Current: Azure Database For Mariadb icon
• ✅ Should be: Azure Database for MariaDB icon (fixes both "For" and "Mariadb")

8. "Transparent" descriptor in alt text (6 files)

These include "Transparent" which describes the image file format, not the content:

Files to update:

• docs/integrations/hosts-operating-systems/index.md
• docs/integrations/hosts-operating-systems/linux.md
• docs/send-data/opentelemetry-collector/install-collector/index.md
• docs/send-data/opentelemetry-collector/install-collector/linux.md
• docs/send-data/opentelemetry-collector/remote-management/source-templates/index.md
• docs/send-data/opentelemetry-collector/remote-management/source-templates/linux/index.md
• ❌ Current: Linux Transparent icon
• ✅ Should be: Linux icon

---

Summary

• Critical fixes (must address before merge): 6 entries
• Style fixes (strongly recommended): ~30 entries
• Verification needed: Azure/Microsoft product name capitalization for "For"

The bulk of the changes (1,962 out of 1,998) look excellent! These issues represent edge cases where image metadata or technical artifacts leaked into the alt text.

[mafsumo]

✅ Fixes Applied

All alt text issues have been resolved. Here's how the corrections were made:

Automated Fix Process

Created a bash script (fix-alt-text-issues.sh) to apply all 36 corrections automatically:

• Used targeted sed commands for each specific issue category
• Organized fixes by priority (critical issues first, then style)
• Created verification script (verify-alt-text-fixes.sh) to confirm all fixes applied correctly

This automated approach ensured:

• Accuracy: Eliminated human error for repetitive changes
• Speed: Applied fixes across 20+ files in seconds
• Verification: Caught 2 additional "Linux Transparent" entries not in the original review table

Why Two Commits

Commit 1 (5b8df853d): "Fix alt text issues identified in review"

• Fixed all 34 issues from the initial review
• Critical fixes: hash IDs, CSS class names, garbled text
• Style fixes: capitalization, brand names

Commit 2 (8a765b0b8): "Fix remaining 'Linux Transparent' alt text entries"

• The verification script caught 2 additional "Linux Transparent" entries that weren't in the original changes table
• Applied to: linux-opentelemetry.md and product-list-a-l.md

All verification checks now pass. The branch is ready for final review.

---

Scripts available in repo root for reference: fix-alt-text-issues.sh, verify-alt-text-fixes.sh, ALT-TEXT-FIX-README.md

[mafsumo]

Approving for merge on Monday