CL
Writing Showcase

Troubleshooting and Best Practices

Learn how to diagnose and fix common search issues, and follow best practices to maintain optimal search performance.

URL Changes and Search Impact

URL changes can significantly disrupt search functionality. Understanding the impact helps you plan and mitigate issues.

How URL Changes Affect Swiftype

When you change a docs page URL that's already indexed:

  1. Swiftype removes the record for the old URL
  2. If a redirect exists, it creates a new record for the new URL
  3. Result rankings are lost and must be re-added manually
  4. Reindexing can take days to over a week

Impact on NR1 Help Center

URL changes create specific problems for the NR1 Help Center:

Critical Issue

When URLs change, NR1 Help Center may show empty content because the docs-library-service queries Swiftype for URLs that no longer exist. This results in null body content until reindexing completes.

The Technical Flow

mermaid
graph TD
    A[User searches in NR1] --> B[NR1 queries NerdGraph]
    B --> C[docs-library-service queries Swiftype]
    C --> D[Swiftype returns old URL]
    D --> E[Service requests JSON at old URL]
    E --> F[URL doesn't exist - returns null]
    F --> G[Empty content in NR1]

Quick Fix Options

  1. Trigger manual recrawl (may take time)
  2. Delete old results and manually add new ones
  3. Update docs-library-service cache for specific terms

Proper canonical links are crucial for avoiding indexing issues and duplicate content.

html
<!-- For page: https://docs.newrelic.com/docs/apm/getting-started/ -->
<head>
  <link
    rel="canonical"
    href="https://docs.newrelic.com/docs/apm/getting-started/"
  />
</head>
  1. Exact URL matching: Canonical link must match resolved URL precisely
  2. Include trailing slashes: Maintain consistency with site structure
  3. Use absolute URLs: Always include full domain
  4. Match subdirectories: Ensure complete path accuracy

Common Canonical Issues

Problem

Cause

Solution

Duplicate indexing

Missing canonical tag

Add proper canonical link

Wrong page ranking

Incorrect canonical URL

Fix canonical to match actual URL

Indexing failures

Canonical/URL mismatch

Align canonical with final resolved URL

Diagnostic Steps

  1. Inspect HTML head for canonical tag presence
  2. Verify URL match between canonical and actual page
  3. Check trailing slash consistency
  4. Test with browser dev tools
bash
# Quick command-line check for canonical links
curl -s "https://docs.newrelic.com/docs/apm/" | grep canonical

# Expected output:
# <link rel="canonical" href="https://docs.newrelic.com/docs/apm/" />

Tools for Canonical Validation

  • Browser dev tools: Inspect head elements
  • SEO browser extensions: Automated canonical checking
  • Command line tools: Bulk canonical validation
  • Swiftype admin: Index record inspection

Common Search Issues

Pages Not Appearing in Results

Symptoms: New or updated pages don't show in search

Diagnosis checklist:

  • Page is publicly accessible
  • No [object Object] meta tag present
  • Canonical link is correct
  • URL includes trailing slash
  • Page has been crawled (check admin)

Solutions:

  1. Manually add URL to Swiftype
  2. Verify sitemap.xml includes page
  3. Trigger manual crawl
  4. Check for robots.txt blocks

Outdated Content in Results

Symptoms: Search shows old version of page

Common causes:

  • Crawler hasn't reindexed
  • Old URL still in index
  • Caching delays

Solutions:

  1. Manual reindex specific page
  2. Delete old record if URL changed
  3. Wait for automatic crawl cycle
  4. Clear docs-library-service cache

Poor Result Relevance

Symptoms: Irrelevant results rank highly

Diagnosis:

  • Review current result rankings
  • Check for synonym conflicts
  • Analyze search query intent
  • Monitor user behavior analytics

Solutions:

  1. Adjust result rankings for term
  2. Add more specific aliases
  3. Create disambiguation content
  4. Remove irrelevant results

Preventive Maintenance

Weekly Tasks

  • Review "no results" searches
  • Check top 10 search terms for issues
  • Monitor crawler error logs
  • Verify new content is indexed

Monthly Tasks

  • Full analytics review
  • Update result rankings for top terms
  • Audit canonical links on new pages
  • Clean up outdated index entries

Quarterly Tasks

  • Comprehensive search quality audit
  • Review and update synonym lists
  • Performance optimization review
  • Documentation updates

Emergency Procedures

Search Completely Down

  1. Check Swiftype service status
  2. Verify API credentials
  3. Test basic search queries
  4. Contact Swiftype support if needed

Critical Page Missing

  1. Manually add URL immediately
  2. Verify page accessibility
  3. Check for indexing blocks
  4. Monitor for successful indexing

Wrong Results for Important Terms

  1. Immediately adjust result rankings
  2. Document changes made
  3. Monitor click-through rates
  4. Follow up with analytics review

TBD Improvements

Future Enhancements

Consider implementing: - Automated canonical link monitoring - Search health dashboards - Proactive indexing alerts - Automated testing for critical search terms - Integration with CI/CD for URL change detection