Skip to content

DOCS-1520 - Rescope the style guide and refresh contributing docs - #7079

Open
kimsauce wants to merge 14 commits into
mainfrom
DOCS-1520
Open

DOCS-1520 - Rescope the style guide and refresh contributing docs#7079
kimsauce wants to merge 14 commits into
mainfrom
DOCS-1520

Conversation

@kimsauce

@kimsauce kimsauce commented Sep 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Purpose of this pull request

Rescopes the Sumo Docs Style Guide so it stops re-documenting generic Docusaurus and Markdown mechanics and keeps only Sumo Logic house rules, with a link out for the rest. Also refreshes stale UI screenshots and trims dead content elsewhere in the contributing section.

Style guide (docs/contributing/style-guide.md)

  • Compress the mechanics-heavy sections — Tabs, Videos, Admonitions, Code blocks, Collapsible text blocks, Downloadable files, Tables — down to the Sumo-specific conventions plus a link to the matching Docusaurus page (~640 lines removed).
  • Intro — introduce Docusaurus ("a static site generator"); replace the Jekyll front-matter link with the Docusaurus one.
  • Doc structure summary — removed; the one useful rule ("open with what / why / who") moved to a Voice and tone bullet.
  • Renames — "Documenting procedures" → "Step headings"; "Import GitHub repo file" → "Embed a file from a GitHub repo"; "Images in lists" promoted from H4 to H3. Nothing links to the old anchors.
  • Add an image — reshaped from a numbered tutorial into a guidance list, matching the register of the other Images subsections.
  • Hub pages — rewritten to document the card grid our index.md pages actually use (box-wrapper / smallbox card), not <DocCardList>.
  • Videos — reframed: the Training Team produces videos; contributors only embed them. Wistia and YouTube shown as tabs, Wistia first.
  • Release notes — the frontmatter step now points at a neighboring post and calls out only the two release-notes-specific fields (hide_table_of_contents, the image logo fallback).
  • Reusing content — example switched to reuse/api-roles.md (imported by ~50 API docs).
  • className="unique-tabs" removed from the guide's own <Tabs> examples and documented as a no-op.
  • Removed style-guide-rescope-plan.md, a planning draft committed here by mistake.

Related contributing-doc updates

  • docs/contributing/create-edit-doc.md — Step 5 aligned to the same hub-page card-grid pattern.
  • docs/reuse/ui-elements.md + static/img/content-sharing/{left-nav,classic-nav-menu}.png — refreshed the left-nav screenshots to the current UI and adjusted widths so the table renders legibly.
  • docs/contributing/index.md — removed the feature-request callout.
  • Deleted the orphaned static/img/contributing/release-notes-dropdown-menu.png.

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)

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

🤖 Generated with Claude Code

@kimsauce kimsauce self-assigned this Sep 1, 2026
@cla-bot cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label Sep 1, 2026
kimsauce and others added 6 commits September 1, 2026 01:34
@kimsauce @claude
DOCS-1520 - Fix the "please" example and "cannot" typo in the style g…
3b85c5c 
…uide

The Error messaging example used "Please", which the style guide's own
"no please" rule forbids. The Contractions example read
`use "cannot", not "cannot"` -- the second should be "can't".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1520 - Fix style guide examples that broke its own rules
d30807e 
The alt-text guidance used "e.g.", which the Abbreviations section says
to avoid; changed to "for example". Also replaced "and/or" with "or".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce
changes
6ffbd07
@kimsauce @claude
DOCS-1520 - Align the Numbers rule with AP, Microsoft, and Google
c4d3c90 
"Always use numerals, even for 2" matched none of the style references.
Switch to the shared convention: spell out zero through nine in prose,
numerals for 10 and up, and always numerals for measurements, versions,
percentages, code, dates, times, UI, and ranges that include 10 or more.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce
fix spellcheck error
4e0b37f
@kimsauce @claude
DOCS-1520 - Add feature name vs. use case capitalization guidance
3d9360d 
From marketing's product-name alignment work (relates to DOCS-64):
coined feature names stay capitalized; generic capabilities and use
cases do not.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
kimsauce and others added 6 commits September 1, 2026 02:50
@kimsauce
Merge remote-tracking branch 'origin/main' into DOCS-1520
b6df05a 
# Conflicts:
#	docs/contributing/style-guide.md
@kimsauce @claude
DOCS-1520 - Add "does it need a name?" gate to Capitalization
7986a99 
Per DOCS-64's references (Kubie's "Fighting Feature Names", Shopify
Polaris, IBM Carbon): default to plain descriptive language and only
brand a feature name when it's genuinely necessary.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce
Merge branch 'main' into DOCS-1520
cd8b84d
@kimsauce @claude
DOCS-1520 - Trim Docusaurus-mechanic repetition from the style guide
4310aaf 
Compress the sections that restated generic Docusaurus/Markdown docs
(Tabs, Videos, Admonitions, Code blocks, Collapsible, Downloadable,
Tables) down to Sumo Logic house rules plus a link out. Also:

- Introduce Docusaurus in the intro; swap the Jekyll frontmatter link
- Fold "Doc structure summary" into a Voice and tone bullet
- Rename "Documenting procedures" -> "Step headings", "Import GitHub repo
  file" -> "Embed a file from a GitHub repo"; promote "Images in lists"
  to H3
- Reshape "Add an image" from a numbered tutorial to a guidance list
- Rewrite "Hub pages" to the real box-wrapper/smallbox card grid, and
  align create-edit-doc.md Step 5 to match
- Reframe "Videos": the Training Team produces them; Wistia/YouTube tabs
- Trim the Release notes frontmatter step to the two release-notes-
  specific fields; drop the now-orphaned release-notes-dropdown-menu.png
- Reuse-content example now uses reuse/api-roles.md (imported ~50x)
- Remove the accidentally committed style-guide-rescope-plan.md

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1520 - Refresh left-nav screenshots in the UI elements table
e1c9a77 
Replace left-nav.png and classic-nav-menu.png with current-UI captures
and adjust the icon/image widths in reuse/ui-elements.md so the table
cells render legibly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce @claude
DOCS-1520 - Remove the feature-request callout from the contributing …
c9dba02 
…index

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce changed the title DOCS-1520 - Update Style Guide DOCS-1520 - Rescope the style guide and refresh contributing docs Sep 2, 2026
@kimsauce
kimsauce marked this pull request as ready for review September 2, 2026 05:01
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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kimsauce