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

[JV0812]

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

[kimsauce]

What would you think about formatting the FAQ questions as H3s? Like this. Maybe it would help LLMs, but could add noise.

[JV0812]

@kimsauce Great Idea. But as you said it will create a lot of noise when we add more number of FAQs. Also, the page nav bar will feel heavy.
For example, we have some docs which have both troubleshooting and FAQs sections. For troubleshooting, we usualy add in H3 - so that the reader is easily able to find the solution for the issue which he is facing. But if we add FAQs too for this page H3 - the page will look very noise and the nav bar will be look packed.
Let me know your thoughts on this.

[kimsauce]

Using bold for the FAQ questions is a reasonable choice for keeping the TOC clean, but it does mean those questions are invisible to answer engines and LLMs from a structural standpoint — bold is purely visual formatting with no semantic weight. H3 headings, on the other hand, create discrete retrievable units that RAG systems can chunk and cite individually, and they match the pattern answer engines use to extract FAQ responses. There's also no heading hierarchy concern here since ## FAQs → ### question is a clean H2→H3 step. Happy to go either way, but H3 would meaningfully improve AEO discoverability.

[JV0812]

Thanks @kimsauce — went with H3/H4 headings for the AEO benefit you described. Applied in 1b3287c:

• FAQ questions directly under an ## H2 FAQ section are now H3 (your clean H2→H3 step) — e.g. sumo-logic-ui.md, universal-connector-source.md, and the top ## FAQs in soc-analyst-agent.md.
• Questions grouped under an existing ### H3 sub-category (e.g. General, Security and privacy, Technical) are now H4, so we don't end up with two different meanings at H3. This covers mobot.md and ai-machine-learning.md.

Each question is now a discrete, citable heading. This also keeps @JV0812's TOC-noise concern in check: Docusaurus shows only H2–H3 in the right-side TOC by default, so the large categorized FAQ lists stay out of the TOC while remaining semantic headings.

I also added a "Format FAQ questions as headings" convention to the style guide documenting the H3/H4 rule for future FAQs.