Skip to content

DOCS-78 - Refactor Get Started with Search categories - #7068

Draft
kimsauce wants to merge 5 commits into
mainfrom
DOCS-78
Draft

DOCS-78 - Refactor Get Started with Search categories#7068
kimsauce wants to merge 5 commits into
mainfrom
DOCS-78

Conversation

@kimsauce

@kimsauce kimsauce commented Aug 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Purpose of this pull request

DO NOT MERGE! UX tree testing.

This pull request reorganizes the "Get Started with Search" documentation section (DOCS-78):

  • Splits the 4 overlapping categories (Search Basics, How to Use the Search Page, Build Searches, Suggested Searches) into 5 clearer ones (Search Basics, Build Searches, Search Results, Manage Searches, Suggested Searches) using Docusaurus's location-independent doc IDs — no files moved, no URLs changed for the reorg itself
  • Orders items within each category using 90 days of GA4 traffic data, while keeping explicitly pedagogical anchors in place (e.g. Search Modes before Autocomplete, Best Practices last)
  • Runs a full title audit so every doc title stands alone out of context (titles surface in Algolia search)
  • Merges two short, closely-related docs into their parents (add-saved-search-to-favorites.md → save-search.md; share-message-link.md → share-link-to-search.md) with matching cid-redirects.json entries
  • Splits non-TOC content out of two category index pages into new about-search-page.md / about-build-search.md pages
  • Adds missing H2 structure to 9 previously flat docs, fixes a heading-hierarchy skip in 2 docs, trims duplicated content between set-time-range.md and time-range-expressions.md, and fixes several smaller content bugs found along the way (a copy-pasted description, duplicate bullets, an undocumented UI icon, awkward phrasing)

Verified against a clean yarn build (no broken links/anchors) throughout.

Not yet addressed from the ticket (flagging for a follow-up pass):

  • Aligning the new IA with the Training Team's learning-path slides and the product roadmap
  • The specific beginner-friendliness gap called out in the ticket (documenting ?<field_name> regex named-capture syntax, which is unrelated to ? as a wildcard)

Select the type of change

  • Update Content - Revisions, updating sections
  • Minor Changes - Typos, formatting, slight revisions
  • 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)

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

kimsauce and others added 4 commits August 26, 2026 00:34
@kimsauce @claude
DOCS-1829 - Reorganize Get Started with Search sidebar into 5 categories
69168c0 
Split the 4 overlapping categories (Search Basics, How to Use the
Search Page, Build Searches, Suggested Searches) into 5 clearer ones:
Search Basics, Build Searches, Search Results, Manage Searches, and
Suggested Searches. Docs are regrouped by category without moving any
files on disk, so no URLs change and no redirects are needed.

Also reorders items within each category to teach fundamentals before
edge cases (e.g. Search Modes and Search Autocomplete now lead Build
Searches; Comments in Search Queries moves to the end of Search
Basics since it depends on already knowing how to write a query).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1829 - Clarify and align titles across Get Started with Search docs
7abaceb 
Sharpen titles so each doc makes sense out of context (e.g. as an
Algolia search result), fix sentence-case heading violations, and
update cross-references and index-page card text to match the new
titles. Also fixes a few awkward or inaccurate sentences flagged
during review (e.g. Search Modes' intro, which previously only
described Basic Mode).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1829 - Merge Add to Favorites and Share Message Link into parent…
ec02429 
… docs

Both were short, closely-related docs that made more sense as
sections of their parent pages:

- Add a Saved Search to Favorites -> merged into Save a Search as
  "Add a saved search to Favorites"
- Share a Link to a Specific Message -> merged into Share a Link to
  a Search as "Share a link to a specific message"

Updates cid-redirects.json (retargets 2 existing legacy redirects and
adds 2 new ones for the retired /docs URLs) and fixes the remaining
cross-reference in get-started/library.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1829 - Reorder sidebar by GA4 traffic, add missing structure, fi…
4867835 
…x content bugs

Sidebar and navigation:
- Reorder items within all 5 Get Started with Search categories using
  90-day GA4 pageview data, keeping explicitly-fixed pedagogical
  anchors in place (orientation pages first, Search Modes before
  Autocomplete before Dynamic Parsing, Best Practices last in Build
  Searches, Comments last in Search Basics)
- Sync all 5 index-page TOC card orders to match
- Split the non-TOC content out of search-page/index.md and
  build-search/index.md into new about-search-page.md and
  about-build-search.md pages, added to sidebars.ts and given proper
  titles/intros/cross-links (about-build-search.md also had its
  "Write efficient search queries" section cut since it fully
  duplicated best-practices-search.md; rescoped to its unique content)

Structure and content fixes:
- Add missing H2 sections to 9 docs that had none (quick-search-
  collectors-sources, search-autocomplete, view-traces-search-results,
  change-time-range-in-histogram, search-from-field-browser,
  show-hide-fields-in-field-browser, log-level, pin-a-search,
  search-highlighting); pin-a-search.md and search-from-field-browser.md
  also had their heading levels promoted to fix an H1-to-H4/H3 skip
- Add missing intro paragraph to set-messages-tab-preferences.md and
  de-duplicate its "Sort by" / "View n messages per page" bullets
- Fix log-level.md's frontmatter description, which was copy-pasted
  from an unrelated doc
- Trim duplicated content between set-time-range.md and
  time-range-expressions.md (DOCS-1830 scope), and cross-link both to
  the canonical time-reference.md doc for time zone details
- Rewrite pause-cancel-search.md's awkward intro and apply the
  "Log Search page" branding decision
- Change "Best approach" to "Recommended" in best-practices-search.md
- Add a missing meter-icon (Scan Estimates) row to about-search-page.md's
  UI reference table
- Retitle wildcards-in-full-text-searches.md and search-modes.md with
  clearer value props

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce self-assigned this Aug 26, 2026
@cla-bot cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label Aug 26, 2026
@kimsauce
kimsauce marked this pull request as draft August 26, 2026 10:34
@kimsauce kimsauce changed the title DOCS-78 - Consolidate overlapping Get Started with Search categories DOCS-78 - Refactor Get Started with Search categories Sep 1, 2026
@kimsauce kimsauce mentioned this pull request Sep 2, 2026
Merged
4 tasks
@kimsauce

kimsauce commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator Author

Merge order: #7061 (DOCS-1827, Query Assist consolidation) should merge before this PR. Both touch search-autocomplete.md, sidebars.ts, and cid-redirects.json. After #7061 lands I'll rebase this branch on main and reconcile search-autocomplete.md — #7061 rewrites that page (folds in the retired query-assist.md), so this PR's title-audit / H2 edits to it will need reapplying onto the new content.

@kimsauce kimsauce added the do-not-merge Pull requests that should not be merged label Sep 2, 2026
@kimsauce @claude
Merge main into DOCS-78 and tighten Get Started with Search labels
7251364 
Resolves two conflicts from PR #7061 (Query Assist consolidation):
- search-autocomplete.md: take main's rewritten body and description,
  keep this branch's retitle intent (now just "Search Autocomplete").
- search-large-messages.md: take main's 256KB facts and Known
  limitations section, keep this branch's retitle and sentence-case
  heading.

Label and SEO cleanup on the Get Started with Search docs:
- Drop the inconsistent "Log" disambiguation prefix from titles
  (kept where "log message/data/entry" is the real noun).
- Make the five category-hub titles grammatically parallel; drop
  "How to" and the doubled "Sumo Logic" (the site title template
  already appends it).
- Fix the one gerund sidebar_label ("Exporting" -> "Export Search
  Results"); drop "Log" from "Save a Log Search".
- Rewrite ~20 weak or vague descriptions to specific, ~120-160 char
  summaries.
- Fix pre-existing content bugs surfaced by the audit: swapped Apache
  access/errors descriptions, "Linux server" in the Cisco ASA parser
  doc (frontmatter and body), stale "Windows 2008" reference.
- Make quick-search-collectors-sources.md consistent on "Data
  Collection page".

Reorder two sidebar categories to match 90-day GA4 traffic:
- Search Basics: move built-in-metadata to position 2 (highest-traffic
  page in the section).
- Build Searches: place use-searchable-time and dynamic-parsing above
  the lower-traffic search-modes and search-autocomplete anchors.

Verified with a full yarn build (no broken links or anchors).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JV0812 JV0812 Awaiting requested review from JV0812 JV0812 is a code owner
@mafsumo mafsumo Awaiting requested review from mafsumo mafsumo is a code owner
@amee-sumo amee-sumo Awaiting requested review from amee-sumo amee-sumo is a code owner

At least 0 approving reviews are required to merge this pull request.

Assignees

@kimsauce kimsauce

Labels

cla-signed Contributor approved, listed in .clabot file do-not-merge Pull requests that should not be merged

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kimsauce