Skip to content

DOCS-1601 - Remove accordion tags from FAQ sections and update style guide#6668

Open
JV0812 wants to merge 2 commits into
mainfrom
remove-accodion-for-FAQ-section
Open

DOCS-1601 - Remove accordion tags from FAQ sections and update style guide#6668
JV0812 wants to merge 2 commits into
mainfrom
remove-accodion-for-FAQ-section

Conversation

@JV0812
Copy link
Copy Markdown
Collaborator

@JV0812 JV0812 commented May 8, 2026

Purpose of this pull request

This PR removes <details> and <summary> accordion tags from FAQ sections to improve accessibility, SEO, and AI citation capabilities. It also updates the style guide with comprehensive guidance on when to use (and when NOT to use) collapsible sections.

Summary

Removed accordion tags from 7 documentation files containing FAQ sections (67 total accordion items). FAQ content is now displayed using bold question headings followed by visible answers. This change ensures FAQ content is immediately visible, scannable, and properly indexed by search engines and AI tools.

Updated the contributing style guide with:

  • Clear table-based DO/DON'T guidelines for collapsible sections
  • GEO (Generative Engine Optimization) principles documentation
  • AI citation failure explanation for hidden content
  • Title attribute requirement for accessibility
  • Proper FAQ formatting examples

What changed

FAQ Documentation (7 files, 67 accordions removed):

  • docs/search/mobot.md (24 items)
  • docs/api/mcp-server.md (3 items)
  • docs/get-started/sumo-logic-ui.md (6 items)
  • docs/get-started/ai-machine-learning.md (11 items)
  • docs/cse/get-started-with-cloud-siem/soc-analyst-agent.md (9 items)
  • docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/microsoft-graph-azure-ad-reporting-source.md (1 item)
  • docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/universal-connector-source.md (13 items)

Style Guide:

  • Added table with 10 use cases showing when to use/not use <details> tags
  • Documented GEO principles and AI citation impacts
  • Added warning callout about FAQ/troubleshooting content
  • Added title attribute requirement for <details> tags
  • Provided proper FAQ formatting example
  • Preserved existing visual examples

Before & After

Before:

<details>
<summary>What is the question?</summary>
Answer text here.
</details>

After:

**What is the question?**

Answer text here.

Why this change matters

  1. GEO Compliance: Hidden content negatively impacts Generative Engine Optimization and search visibility
  2. AI Citation: AI tools and search engines cannot properly cite content hidden inside accordion components
  3. Accessibility: FAQ content must be immediately visible and scannable for all users
  4. User Experience: Eliminates friction of clicking to reveal FAQ answers

Testing Plan

  • Local build verified at http://localhost:3000/
  • Reviewed all 7 FAQ pages for proper display
  • Verified style guide table renders correctly
  • Confirmed no broken links or formatting issues
  • Checked that remaining <details> tags (code samples, installation methods) are properly used

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-1601

Select the type of change

  • Documentation content

…guide

Removed <details> and <summary> accordion tags from FAQ sections across 7 documentation files (67 total accordions). FAQ content is now displayed as bold headings followed by visible answers, improving accessibility, SEO, and AI citation capabilities.

Updated the style guide with comprehensive guidance on when to use and NOT use collapsible sections:
- Added table format with clear DO/DON'T guidelines for 10 use cases
- Documented that accordion tags violate GEO (Generative Engine Optimization) principles
- Explained that AI tools cannot properly cite content hidden in accordions
- Added requirement for title attribute in <details> tags for accessibility
- Provided proper FAQ formatting examples
- Preserved existing visual examples

Changes:
- Converted 67 FAQ accordion items to visible bold format
- Updated 7 FAQ documentation files
- Enhanced style guide with table-based guidance
- Added GEO and AI citation best practices

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@cla-bot cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label May 8, 2026
@JV0812 JV0812 self-assigned this May 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed Contributor approved, listed in .clabot file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant