diff --git a/.claude/commands/audit-doc.md b/.claude/commands/audit-doc.md index cdaf1d4051..ebdc0288ad 100644 --- a/.claude/commands/audit-doc.md +++ b/.claude/commands/audit-doc.md @@ -1,18 +1,12 @@ # Audit Doc — Documentation Quality Check -Performs comprehensive quality checks on documentation files to ensure adherence to Sumo Logic style guidelines, proper structure, and completeness. +Use this command to audit a doc for Sumo Logic style, structure, links, and frontmatter compliance — run it before submitting any PR, after creating a new doc, or when reviewing community contributions. -## What this command does +## Gotchas -When you invoke `/audit-doc`, Claude will: - -1. **Read and analyze the specified doc file** -2. **Check frontmatter**. Validate required fields and format -3. **Review content structure**. Check headings, sections, and organization -4. **Validate links and images**. Check paths, alt text, and references -5. **Check style adherence**. Apply Sumo Logic style guide rules -6. **Report findings**. Provide detailed feedback with specific line numbers -7. **Suggest fixes**. Offer actionable recommendations +- H1 headings and the `title` frontmatter field use **Title Case**. H2, H3, H4 use **sentence case** (only first word and proper nouns capitalized). +- Skip warnings for legacy docs with an established style, docs tagged `noindex` (temporary drafts), or third-party content not meant to be modified. +- `/audit-doc` does not check SEO/AEO/GEO signals — run `/seo-audit` separately for discoverability. ## When to use this command @@ -20,7 +14,6 @@ When you invoke `/audit-doc`, Claude will: * After creating a new doc to validate structure * When updating existing docs to ensure consistency * To identify broken links or missing images -* To verify adherence to Sumo Logic style guidelines * When reviewing community contributions ## Workflow @@ -67,7 +60,7 @@ Check for required fields and proper formatting: * [ ] Only one H1 heading (the title in frontmatter) * [ ] H2 sections used for main sections * [ ] No skipped heading levels (H2 → H4 without H3) -* [ ] Headings use Title Case +* [ ] H1 uses Title Case; H2, H3, H4 use sentence case (only first word and proper nouns capitalized) **Required sections (by doc type):** @@ -301,53 +294,6 @@ After presenting the audit report, ask the user if they would like Claude to: * Unclear instructions * Not linked from parent page -## Example usage - -### Basic audit - -``` -User: "/audit-doc docs/integrations/databases/postgresql.md" - -Claude: -1. Reads the file -2. Checks frontmatter (id, title, description, tags) -3. Validates structure (headings, sections) -4. Checks links and images -5. Applies style guide rules -6. Generates report with: - - 2 critical issues (missing image, broken link) - - 3 warnings (description too long, inconsistent formatting) - - 5 suggestions (add example, improve heading) -7. Asks if user wants fixes applied -``` - -### Audit with doc type - -``` -User: "/audit-doc docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md --type c2c-source" - -Claude: -1. Reads the file -2. Applies C2C source-specific checks -3. Validates vendor configuration section -4. Checks authentication setup steps -5. Verifies required sections present -6. Reports findings specific to C2C sources -``` - -### Audit directory - -``` -User: "/audit-doc docs/integrations/security-threat-detection/" - -Claude: -1. Finds all .md files in directory -2. Runs audit on each file -3. Generates summary report for all files -4. Highlights files needing attention -5. Provides batch fix option -``` - ## Audit checklist summary Use this checklist template for the report: @@ -420,63 +366,9 @@ Track common issues across multiple audits to identify systemic problems. * Validate CID URL mapping * Confirm cross-references -## Tips and best practices - -**For effective audits:** -* Run audit before requesting PR review -* Fix critical issues first, then warnings -* Use audit reports in PR descriptions -* Re-run audit after making fixes -* Consider doc type context (release notes vs feature docs) - -**Common quick fixes:** -* Add missing frontmatter fields -* Update relative link paths -* Add language tags to code blocks -* Fix heading capitalization -* Remove trailing whitespace - -**When to skip warnings:** -* Legacy docs with established style -* Marketing pages with intentional tone -* Third-party content that shouldn't be modified -* Temporary draft content (with noindex tag) - -## Error handling - -**If file not found:** -* Show error message -* Suggest using Tab completion for path -* Check if file was recently moved or renamed - -**If file is not markdown:** -* Show error: "Audit only works with .md files" -* Suggest appropriate file type - -**If doc type cannot be determined:** -* Ask user to specify doc type -* Provide list of supported types -* Offer generic audit without type-specific checks - -**If many issues found (>20):** -* Suggest focusing on critical issues first -* Offer to generate summary instead of full report -* Recommend gradual fixes in multiple PRs - -## References - -* [Sumo Logic Style Guide](/docs/contributing/style-guide) -* [Contributing Guide](/docs/contributing) -* [Doc Templates](/docs/contributing/templates) -* [Docusaurus Documentation](https://docusaurus.io/docs) - ---- - ## Related commands -`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not -check SEO/AEO/GEO signals. For discoverability, run both: +`/audit-doc` covers structure, style, links, frontmatter, and required sections. It does not check SEO/AEO/GEO signals. For discoverability, run both: * **`/seo-audit`** — checks title length, description quality, question headings, GEO patterns * **`/geo-optimize`** — rewrites content to improve AI citation and search visibility -* **`/tone-check`** — checks voice and tone against Sumo Logic style rules (standalone voice check) diff --git a/.claude/commands/doc.md b/.claude/commands/doc.md index 13fbc78697..17b08c3e31 100644 --- a/.claude/commands/doc.md +++ b/.claude/commands/doc.md @@ -1,18 +1,6 @@ # Create New Doc -Automates the creation of general Sumo Logic documentation for features, how-tos, concepts, reference pages, and troubleshooting guides. - -## What this command does - -When you invoke `doc`, Claude will guide you through: - -1. **Determine doc type**. Feature, how-to, concept, reference, or troubleshooting. -2. **Gather information**. Title, description, file path, and keywords. -3. **Create markdown file**. Generate file with proper frontmatter and basic structure. -4. **Add to navigation**. Guide on adding to sidebars.ts. -5. **Add to hub page**. Suggest adding card to parent index page. -6. **Create CID mapping**. Add permanent URL if needed for UI links. -7. **Validate and preview**. Check structure and provide next steps. +Use this command to create a new feature doc, how-to, concept, reference, or troubleshooting guide — it scaffolds the file, frontmatter, structure, and sidebar entry. ## When to use this command @@ -386,40 +374,6 @@ Before finishing, verify: * [ ] No negative contractions (use "cannot", "will not", "do not"). * [ ] No trailing whitespace. -## Example usage - -### Feature Doc Example - -``` -User: "Create a doc for the new access keys feature" - -Claude: -1. Confirms type: Feature Documentation -2. Gathers info: title, path, description, keywords -3. Creates: docs/manage/security/access-keys.md -4. Generates frontmatter with proper fields -5. Scaffolds feature doc structure -6. Guides on adding to sidebars.ts under Manage category -7. Suggests adding card to docs/manage/security/index.md -8. Asks if CID mapping needed -9. Provides validation checklist -``` - -### How-to Guide Example - -``` -User: "Create a how-to guide for installing the OpenTelemetry Collector on Windows" - -Claude: -1. Confirms type: How-to Guide -2. Gathers info: title, path, description -3. Creates: docs/send-data/opentelemetry-collector/install-collector/windows.md -4. Generates frontmatter -5. Scaffolds how-to structure with prerequisites and steps -6. Guides on sidebar placement -7. Provides checklist -``` - ## Common patterns ### File path conventions @@ -472,120 +426,3 @@ keywords: - reports ``` -## Safety principles - -* **Check existing files** before creating to avoid duplicates. -* **Follow existing path conventions** in the category. -* **Use descriptive filenames** that indicate content. -* **Keep titles concise** but clear. -* **Validate frontmatter** has all required fields. -* **Use appropriate structure** for the doc type. - -## Post-completion message - -After successfully creating the doc, tell the user: - -``` -✅ Documentation file created successfully! - -File created: -* 📄 {file-path} - -Summary: -* Type: {doc-type} -* Title: {title} -* Category: {category} - -Next steps: -1. Add content to the doc sections -2. Add doc to sidebars.ts: - * Open sidebars.ts - * Find the {category} category - * Add '{doc-id}' to the items array -3. Optional: Add card to hub page at {parent-index-path} -4. Optional: Create CID mapping in cid-redirects.json -5. Preview locally: yarn start -6. Check preview at: http://localhost:3000/docs/{doc-path} -7. Submit PR: "DOCS-XXX - Add {doc-title}" - -Checklist: -* [ ] Content complete and follows structure. -* [ ] Added to sidebars.ts. -* [ ] Added to hub page (if applicable). -* [ ] CID mapping created (if needed). -* [ ] All links work. -* [ ] Style guide compliant. - -The doc will appear in the navigation menu after you add it to sidebars.ts. - -Would you like me to help add content to any specific section? -``` - -## Error handling - -**If file already exists:** -* Show existing file path and title. -* Ask if user wants to: - * Edit existing file instead. - * Use different filename. - * Overwrite (requires confirmation). - -**If title is too long:** -* Show character count. -* Suggest shorter alternative. -* Recommend using `sidebar_label` for long titles. - -**If path does not follow conventions:** -* Suggest correct path based on category. -* Explain repo conventions. - -**If no description provided:** -* Explain importance for SEO. -* Suggest generating description from title. - -## Tips and best practices - -**General:** -* Start with a clear introduction that sets expectations. -* Use second person ("you") to address readers. -* Keep paragraphs short (2-4 sentences). -* Use active voice. -* Include concrete examples. - -**Structure:** -* Use headings to organize content logically. -* Put most important information first. -* Group related information together. -* End with related topics or next steps. - -**Links:** -* Link to related docs for additional context. -* Use descriptive link text. -* Prefer relative paths for internal links. -* Test all links work. - -**Images:** -* Use images to illustrate UI steps or concepts. -* Always include descriptive alt text. -* Store images in `/static/img/` directory. -* Optimize image file sizes. - -**Code:** -* Specify language for syntax highlighting. -* Keep code examples concise and relevant. -* Include comments for complex code. -* Show realistic examples, not placeholders. - -## References - -* [Style Guide](/docs/contributing/style-guide). -* [Create or Edit a Doc](/docs/contributing/create-edit-doc). -* [Sumo Logic Word List](/docs/contributing/word-list). - ---- - -**Note:** This command is for general documentation. For specialized content types, use the appropriate command: - -* **App integrations**. Use `/app-doc` for creating app documentation with standardized templates and structure. -* **Cloud-to-Cloud sources**. Use `/c2c-source-doc` for Cloud-to-Cloud source integration documentation. -* **Release notes**. Use `/release-note-cse`, `/release-note-collector`, `/release-note-csoar`, `/release-note-developer`, or `/release-note-service` for product release notes. diff --git a/.claude/commands/geo-optimize.md b/.claude/commands/geo-optimize.md index 6710532404..1b28d98764 100644 --- a/.claude/commands/geo-optimize.md +++ b/.claude/commands/geo-optimize.md @@ -125,8 +125,7 @@ After the user confirms which changes to make: After applying changes, tell the user: - Which checks in `/seo-audit` this resolves -- Whether any remaining GEO suggestions need a larger rewrite (offer `/rewrite-intro` if the opening paragraph needed major work) -- Whether the doc would benefit from a `/tone-check` pass afterward +- Whether any remaining GEO suggestions need a larger rewrite (offer to rewrite the opening paragraph if it needed major work) --- @@ -227,4 +226,4 @@ After the first use, the abbreviation alone is fine. * Preserve technical accuracy above all else — if a rewrite would require fact-checking, flag it and ask the user to verify * Do not alter frontmatter except `description` if explicitly requested * Keep the Sumo Logic voice — do not make the doc sound like a Wikipedia article -* If a section is very long and difficult to restructure safely, recommend `/rewrite-intro` or `/simplify` instead of attempting a full rewrite here +* If a section is very long and difficult to restructure safely, flag it and ask the user how they'd like to proceed instead of attempting a full rewrite here diff --git a/.claude/commands/rewrite-intro.md b/.claude/commands/rewrite-intro.md deleted file mode 100644 index f460af749c..0000000000 --- a/.claude/commands/rewrite-intro.md +++ /dev/null @@ -1,315 +0,0 @@ -# Rewrite Intro — Documentation Opening Paragraph Rewrite - -Rewrites the intro/opening paragraph of a documentation page to match Sumo Logic voice and tone standards. - -## What this command does - -When you invoke `/rewrite-intro`, Claude will: - -1. **Fetch the style guide**. Get latest voice and tone rules from live style guide -2. **Read the documentation file**. Analyze the current introduction -3. **Identify issues**. Find voice/tone violations, branding issues, clarity problems -4. **Rewrite the intro**. Create a new opening that matches Sumo Logic standards -5. **Present changes**. Show before/after with explanation of what changed -6. **Apply edits**. Update the file with user approval - -## When to use this command - -* Improving existing documentation intros that don't match Sumo Logic voice -* Converting formal or stiff language to conversational tone -* Fixing branding issues (missing app/source openers) -* Simplifying overly complex opening paragraphs -* Applying 8th-grade reading level to introductions -* Fixing passive voice in opening content - -## Workflow - -### Step 1: Fetch Style Guide - -Before rewriting, always fetch the live style guide: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These contain the authoritative voice and tone rules. - -### Step 2: Get the File - -Ask the user which file to rewrite if not specified. Accept: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename only**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Current Intro - -Read the file and identify: - -1. **The introduction section** - - Usually first 1-3 paragraphs after frontmatter - - Before the first H2 heading - - May include multiple paragraphs - -2. **Document type** - - App doc (requires app opener) - - C2C source doc (requires source opener) - - Feature documentation - - Tutorial or guide - - Release note - -3. **Current issues** - - Voice and tone violations - - Branding compliance - - Reading level - - Clarity and conciseness - -### Step 4: Apply Rewrite Rules - -#### Branding Requirements - -**App docs MUST open with:** -```markdown -The Sumo Logic app for [Vendor] [what it does and why you'd use it]. -``` - -Examples: -- "The Sumo Logic app for AWS CloudTrail provides comprehensive visibility into AWS API activity and security events." -- "The Sumo Logic app for Salesforce helps you monitor user activity, track performance, and analyze security events." - -**C2C source docs MUST open with:** -```markdown -The Sumo Logic source for [Vendor] [what it does]. -``` - -Examples: -- "The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events." -- "The Sumo Logic source for GitHub ingests repository events, pull request activity, and security alerts." - -#### Voice and Tone Principles - -**Address reader as "you":** -- ❌ "Users can configure the source" -- ✅ "You can configure the source" -- ❌ "One should consider performance" -- ✅ "You should consider performance" - -**Active voice:** -- ❌ "Data is collected by the Collector" -- ✅ "The Collector collects data" -- ❌ "Logs are parsed and indexed" -- ✅ "Sumo Logic parses and indexes logs" - -**Conversational but professional:** -- ❌ "This document delineates the methodology for configuration" -- ✅ "This guide explains how to configure the source" -- ❌ "Utilize the subsequent instructions" -- ✅ "Follow these steps" - -**8th-grade reading level:** -- Short sentences (under 20 words) -- Common words over technical jargon -- Simple sentence structure -- One idea per sentence - -**No "please" in directives:** -- ❌ "Please configure the source" -- ✅ "Configure the source" -- ❌ "Please refer to the documentation" -- ✅ "Learn more in the documentation" - -**Use "need to" not "must":** -- ❌ "You must configure authentication" -- ✅ "You need to configure authentication" - -**No filler adjectives:** -- ❌ "very important", "simply click", "just add", "easy to use", "straightforward process" -- ✅ Remove or rewrite without filler - -**Spell out negative contractions:** -- ❌ "can't", "won't", "don't", "isn't" -- ✅ "cannot", "will not", "do not", "is not" - -#### Introduction Structure - -Good intros typically follow this pattern: - -1. **What this is** (1-2 sentences) - - For apps: Branded opener + what it monitors - - For sources: Branded opener + what data it collects - - For features: What the feature does - -2. **Why you'd use it** (1-2 sentences) - - Key benefits - - Main use cases - - Problems it solves - -3. **What you'll learn** (1 sentence, optional for tutorials/guides) - - "This guide shows you how to..." - - "You'll learn to..." - -**Example - App doc intro:** -```markdown -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. The app includes dashboards that help you monitor user activity, detect security threats, and maintain compliance. This guide shows you how to install the app and configure data collection. -``` - -**Example - Source doc intro:** -```markdown -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. This guide explains how to configure the source and verify data collection. -``` - -### Step 5: Present Rewrite - -Show the user: - -```markdown -## Current intro -[Show original text with line numbers] - -## Rewritten intro -[Show new text] - -## Changes made -- Fixed passive voice in sentence 2: "data is collected" → "the source collects data" -- Added proper app opener branding: "The Sumo Logic app for [Vendor]..." -- Removed filler words: "simply", "just", "easy" (3 instances) -- Spelled out "can't" → "cannot" -- Broke 42-word sentence into two shorter sentences -- Changed "users can" → "you can" (addressing reader directly) -- Simplified "utilize" → "use", "in order to" → "to" -- Reduced reading level from 11th grade to 8th grade -``` - -Be specific about what changed and why. - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the intro section -2. **Preserve all other content**. only replace the intro paragraphs -3. **Maintain formatting**. keep existing markdown structure, images, code blocks -4. **Confirm success**. Let user know the changes were applied - -## Safety Guidelines - -- **NEVER modify files automatically**. always show the rewrite and get user approval first -- **Preserve existing content**. only replace the intro section, don't touch anything else -- **Maintain formatting**. keep existing markdown structure, line breaks, spacing -- **Don't change frontmatter**. unless specifically asked -- **Verify document type**. apply correct branding rules (app vs. source vs. feature) - -## Edge Cases - -### No intro exists -If the doc has no introduction: -- Offer to write one from scratch -- Use document type to determine opener format -- Ask user for key information (what it does, why use it) - -### Intro is already good -If intro already meets standards: -- Tell the user it's in good shape -- Suggest only minor tweaks if any -- Don't rewrite just for the sake of rewriting - -### Multiple intro paragraphs -If there are 3+ intro paragraphs: -- Ask user which paragraphs to include in rewrite scope -- Consider if all are needed (may be too long) -- Suggest condensing if appropriate - -### Different doc types -Apply appropriate rules: -- **App docs**: Must have app opener -- **Source docs**: Must have source opener -- **Feature docs**: No special opener, focus on clarity -- **Tutorials**: Include "what you'll learn" -- **Release notes**: Different format, may not need rewrite - -### Technical content -If intro contains necessary technical terms: -- Keep technical terms that are unavoidable -- Define acronyms on first use -- Simplify surrounding prose -- Don't sacrifice accuracy for simplicity - -## Examples - -### Example 1: App Doc - -**User:** `/rewrite-intro docs/integrations/amazon-aws/cloudtrail.md` - -**Original:** -``` -CloudTrail is utilized by organizations to monitor AWS API activity. The application can be used by users to gain visibility into account activity. Data is collected and visualized through various dashboards which are very helpful for security teams. -``` - -**Rewritten:** -``` -The Sumo Logic app for AWS CloudTrail provides visibility into AWS account activity and API usage. You can monitor user actions, detect security threats, and maintain compliance with pre-built dashboards and alerts. -``` - -**Changes:** -- Added proper app opener: "The Sumo Logic app for AWS CloudTrail" -- Changed passive voice: "Data is collected" → "You can monitor" -- Addressed reader as "you" instead of "users" -- Removed filler: "very helpful" -- Simplified: "utilized" → "provides", "gain visibility" → "monitor" -- Combined ideas into two focused sentences - -### Example 2: Source Doc - -**User:** `/rewrite-intro docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/okta-source.md` - -**Original:** -``` -This source integration is designed to collect logs from Okta. Users must configure the source properly. The logs that are collected can include authentication events and system logs. -``` - -**Rewritten:** -``` -The Sumo Logic source for Okta collects authentication logs, system logs, and user activity events from your Okta organization. You can use this data to monitor login patterns, detect suspicious activity, and audit user permissions. -``` - -**Changes:** -- Added proper source opener: "The Sumo Logic source for Okta" -- Removed passive voice: "logs that are collected" → "collects authentication logs" -- Changed "Users must" → "You can" -- Added value proposition (what you can do with the data) -- More specific about log types - -### Example 3: Feature Doc - -**User:** `/rewrite-intro docs/metrics/introduction.md` - -**Original:** -``` -Metrics are utilized within Sumo Logic to provide quantitative measurements of your infrastructure and applications. This functionality is very powerful and can be used by organizations to monitor performance. The system enables users to create visualizations. -``` - -**Rewritten:** -``` -Metrics provide quantitative measurements of your infrastructure and applications. You can track performance trends, set up alerts, and create visualizations to monitor system health in real time. -``` - -**Changes:** -- Removed passive voice: "are utilized" → "provide" -- Changed "users" → "You" -- Removed filler: "very powerful" -- Simplified: "This functionality" → direct statement -- Added specific use cases (track, alert, visualize) - -## Tips for Good Rewrites - -1. **Lead with value**. Start with what it is and what it does, not background -2. **Be specific**. "monitor login patterns" not "gain visibility" -3. **Show benefits**. Tell the reader why they should care -4. **Keep it short**. 2-3 sentences is usually enough for an intro -5. **Match document type**. Apps and sources have specific openers -6. **Test reading level**. Read it aloud; if it sounds stiff, simplify -7. **Focus on the user**. "You can..." not "This allows users to..." - -## After the Rewrite - -Once applied, suggest: -- Review the rest of the document for similar issues -- Consider using `/tone-check` on the full file -- Verify that the intro flows into the next section diff --git a/.claude/commands/seo-audit.md b/.claude/commands/seo-audit.md index c31de4d476..4aed35f5ec 100644 --- a/.claude/commands/seo-audit.md +++ b/.claude/commands/seo-audit.md @@ -1,26 +1,6 @@ # SEO/AEO/GEO Audit — Search and AI Discoverability Check -Audits documentation for search engine optimization (SEO), answer engine optimization (AEO), and generative engine optimization (GEO) signals. Produces a prioritized report and offers to apply fixes. - -## What this command does - -When you invoke `/seo-audit`, Claude will: - -1. **Read the specified file or directory** -2. **Check SEO signals**. Title length, meta description, keywords, heading structure -3. **Check AEO signals**. Question-format headings, direct answers, featured snippet readiness -4. **Check GEO signals**. Authoritative statements, structured facts, LLM citation patterns -5. **Check internal linking**. Presence of links, descriptive anchor text -6. **Generate a prioritized report**. Issues ranked by impact -7. **Offer to fix issues**. Apply improvements with user approval - -## When to use this command - -* Before submitting a PR for new or updated content -* Auditing a section or category for discoverability gaps -* Preparing docs for a product launch or announcement -* Quarterly content health checks -* After rewriting or restructuring a doc +Use this command to audit a doc for SEO, AEO, and GEO signals — run it before any PR on new or updated content, even if you're not focused on search optimization. ## Signal definitions @@ -60,7 +40,6 @@ Use the Read tool to read the complete file content including frontmatter. **Headings** * [ ] No H1 in body — title frontmatter generates H1; a second H1 breaks SEO — **Critical** if present -* [ ] H2 used for main sections; no skipped heading levels (H2 → H4 without H3) — **Warning** if skipped * [ ] At least 2 H2 headings for pages over 500 words — **Suggestion** if none * [ ] No duplicate headings at the same level — **Warning** if duplicated * [ ] Headings are under 60 characters — **Suggestion** if over @@ -161,6 +140,7 @@ Do not modify files without explicit user approval. | `title` over 60 chars | Truncated in search results; first 60 chars carry the most weight | | H1 in body | Duplicate H1 confuses search engines and breaks page structure | | Missing image alt text | Accessibility failure; images are invisible to search crawlers | +| `slug` on regular page | Overrides URL derived from file path; breaks sidebar linking | ### Warnings @@ -202,10 +182,8 @@ Then ask if the user wants to drill into any specific file. ## Tips -* Run this before `/audit-doc` to prioritize discoverability fixes first * Run this after `/geo-optimize` to verify improvements were applied * For batch fixes on description length, `/seo-audit` + `/geo-optimize` together cover most GEO gaps -* Pair with `/tone-check` for comprehensive pre-PR review --- @@ -215,4 +193,3 @@ Then ask if the user wants to drill into any specific file. * **`/audit-doc`** — structure, required sections, broken links, frontmatter completeness, style guide * **`/geo-optimize`** — apply GEO improvements after this audit identifies gaps -* **`/tone-check`** — voice and tone check (standalone; not covered here) diff --git a/.claude/commands/simplify.md b/.claude/commands/simplify.md deleted file mode 100644 index abdefb2024..0000000000 --- a/.claude/commands/simplify.md +++ /dev/null @@ -1,395 +0,0 @@ -# Simplify — Documentation Content Simplification - -Simplifies overly complex, verbose, or hard-to-understand documentation content to meet 8th-grade reading level standards. - -## What this command does - -When you invoke `/simplify`, Claude will: - -1. **Read target content**. Get the file, section, or text to simplify -2. **Analyze complexity**. Identify reading level, passive voice, long sentences, jargon -3. **Rewrite content**. Simplify while maintaining technical accuracy -4. **Present comparison**. Show before/after with complexity analysis -5. **Apply changes**. Update with user approval - -## When to use this command - -* Content is too technical or wordy -* Reading level above 8th grade -* Long, complex sentences (20+ words) -* Excessive passive voice -* Unnecessary jargon or filler words -* User feedback that docs are "hard to understand" -* Preparing content for broader audience - -## Workflow - -### Step 1: Get Target Content - -Ask the user to specify what to simplify: - -**Option 1: Full file** -``` -/simplify docs/send-data/collect-from-other-sources/azure-monitoring.md -``` -Simplifies the entire document. - -**Option 2: Specific section** -``` -/simplify the Prerequisites section in docs/integrations/saas-cloud/salesforce.md -``` -Simplifies just that section. - -**Option 3: Line range** -``` -/simplify lines 45-78 in docs/metrics/introduction.md -``` -Simplifies specific lines. - -**Option 4: User provides text** -User pastes text directly for simplification. - -### Step 2: Analyze Complexity - -Check for these complexity indicators: - -#### Reading Level -- **Above 8th grade?** Needs simplification -- Use short words, simple sentences -- One idea per sentence - -**Tools to assess:** -- Long words (3+ syllables) -- Sentence length (words per sentence) -- Complex sentence structures - -#### Passive Voice -Passive voice makes content harder to read. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" - -#### Long Sentences -Sentences over 20 words are hard to follow. - -❌ **Too long (42 words):** -"In order to configure the source properly, you need to navigate to the Cloud-to-Cloud Integration page in Sumo Logic, select the appropriate integration type from the dropdown menu, and then enter your authentication credentials in the fields provided." - -✅ **Broken up:** -"To configure the source, go to the Cloud-to-Cloud Integration page in Sumo Logic. Select your integration type from the dropdown menu. Enter your authentication credentials in the fields." - -#### Jargon and Technical Terms -Undefined jargon confuses readers. - -❌ **Undefined jargon:** -- "Instantiate a new collector" -- "Leverage the API endpoint" -- "Utilize the following methodology" - -✅ **Plain language:** -- "Create a new collector" -- "Use the API endpoint" -- "Follow these steps" - -**When technical terms are necessary:** -- Define acronyms on first use: "Application Load Balancer (ALB)" -- Provide context: "The collector (a lightweight agent that sends data)" -- Link to glossary if available - -#### Filler Words -Remove these unnecessary words: - -| Filler | Example | Better | -|--------|---------|--------| -| simply | simply click the button | click the button | -| just | just add the field | add the field | -| very | very important | important | -| easy | easy to configure | configure | -| straightforward | straightforward process | (remove or rewrite) | -| actually | actually sends data | sends data | -| basically | basically allows you | allows you | - -#### Nested Clauses -Multiple commas and dependent clauses make sentences hard to parse. - -❌ **Nested (hard to read):** -"The collector, which runs on your infrastructure, collects logs from various sources, including applications, servers, and network devices, and then sends them to Sumo Logic, where they are parsed and indexed." - -✅ **Simplified:** -"The collector runs on your infrastructure and collects logs from applications, servers, and network devices. It sends the logs to Sumo Logic for parsing and indexing." - -#### Redundancy -Common redundant phrases: - -| Replace | With | -|---------|------| -| in order to | to | -| due to the fact that | because | -| at this point in time | now | -| in the event that | if | -| prior to | before | -| subsequent to | after | -| a number of | several, many | -| is able to | can | -| in close proximity to | near | -| for the purpose of | to, for | -| has the ability to | can | -| at the present time | now | - -### Step 3: Apply Simplification Rules - -#### Sentence Structure Rules - -1. **Keep sentences under 20 words** - - Average 15-17 words per sentence - - Vary sentence length for readability - - One main idea per sentence - -2. **Use active voice** - - Subject performs the action - - More direct and clear - - Easier to understand - -3. **Start with the action or subject** - - Don't bury the main point - - Front-load important information - - Avoid long introductory clauses - -4. **Break up complex sentences** - - Multiple ideas → multiple sentences - - Dependent clauses → independent sentences - - Use periods instead of commas - -#### Word Choice Rules - -1. **Use common words** - - "use" not "utilize" - - "start" not "initiate" - - "end" not "terminate" - - "get" not "obtain" - -2. **Replace jargon** - - Technical terms → plain language when possible - - Define acronyms on first use - - Provide context for unfamiliar concepts - -3. **Remove filler adjectives** - - Delete: very, simply, just, easy, straightforward - - Only keep if adds meaning - -4. **Spell out contractions** - - Negative contractions: can't → cannot - - Keep common positive: you'll, they're, we're - -#### Paragraph Structure Rules - -1. **Keep paragraphs short** - - 3-5 sentences maximum - - One main point per paragraph - - Use white space for readability - -2. **Lead with the main point** - - Topic sentence first - - Supporting details after - - Don't bury the lead - -3. **Use bullets for lists** - - 3+ similar items → bullet list - - Easier to scan - - Better comprehension - -### Step 4: Simplification Examples - -#### Example 1: Passive Voice + Jargon - -**Original (Grade 12):** -``` -The data is ingested by the collector which then utilizes various parsing methodologies to transform the logs into a structured format that can be leveraged by the analytics engine. -``` - -**Simplified (Grade 8):** -``` -The collector ingests data and parses logs into a structured format. You can then use this data in the analytics engine. -``` - -**Changes:** -- Passive → active: "data is ingested" → "collector ingests" -- Removed jargon: "utilizes" → "parses", "leveraged" → "use" -- Split 31-word sentence into two shorter sentences (10 and 11 words) -- Added "you" to engage reader - -#### Example 2: Long Sentence + Nested Clauses - -**Original (Grade 13):** -``` -In order to configure the AWS CloudTrail source, which collects API activity logs from your AWS account, you need to first navigate to the Sumo Logic console, then select the Manage Data option from the left navigation menu, and finally click on Collection in order to access the configuration page where you can add a new source. -``` - -**Simplified (Grade 7):** -``` -To configure the AWS CloudTrail source, go to the Sumo Logic console. Select **Manage Data** from the left menu, then click **Collection**. This opens the configuration page where you can add the source. The source collects API activity logs from your AWS account. -``` - -**Changes:** -- Removed "in order to" → "To" (2 instances) -- Split 52-word sentence into 4 shorter sentences (9, 10, 11, 10 words) -- Removed nested clause, moved to separate sentence -- Added bold formatting for UI elements -- More direct instructions - -#### Example 3: Technical Jargon - -**Original (Grade 14):** -``` -The application leverages a sophisticated algorithm to instantiate correlations between disparate data points, thereby enabling users to ascertain patterns that would otherwise remain obfuscated within the raw log data. -``` - -**Simplified (Grade 8):** -``` -The app finds connections between different data points. This helps you spot patterns that are hard to see in raw logs. -``` - -**Changes:** -- "leverages" → "uses" (then simplified to implicit) -- "instantiate correlations" → "finds connections" -- "disparate" → "different" -- "ascertain patterns" → "spot patterns" -- "remain obfuscated" → "hard to see" -- Split into two short sentences (8 and 11 words) - -#### Example 4: Filler Words + Redundancy - -**Original (Grade 10):** -``` -Simply navigate to the configuration page and just enter your credentials. This is a very straightforward process that is actually quite easy to complete, due to the fact that the interface is basically self-explanatory. -``` - -**Simplified (Grade 6):** -``` -Go to the configuration page and enter your credentials. The interface is self-explanatory. -``` - -**Changes:** -- Removed fillers: "Simply", "just", "very", "actually quite", "basically" -- Removed redundancy: "due to the fact that" → (removed) -- "navigate to" → "Go to" -- Cut from 28 words to 13 words -- More direct and confident - -### Step 5: Present Simplified Version - -Show the user: - -```markdown -## Original -**Reading level:** 12th grade -**Average sentence length:** 28 words -**Passive voice:** 4 instances - -[Original text] - -## Simplified -**Reading level:** 8th grade -**Average sentence length:** 14 words -**Passive voice:** 0 instances - -[Simplified text] - -## Changes made -- Broke 3 long sentences (25+ words) into 7 shorter sentences -- Changed 4 passive voice constructions to active voice -- Removed jargon: "instantiate" → "create", "utilize" → "use", "leverage" → "use" -- Removed filler words: "simply", "very", "just" (5 instances) -- Defined acronym: ALB (Application Load Balancer) -- Removed redundancy: "in order to" → "to" (3 instances) -- Split complex paragraph into two focused paragraphs -- Reduced word count from 247 to 178 words (28% reduction) -``` - -### Step 6: Apply Changes - -After user approval: - -1. **Use Edit tool** to replace the content -2. **Preserve structure**. keep headings, lists, code blocks unchanged -3. **Maintain formatting**. line breaks, markdown syntax -4. **Confirm success** - -## Safety Guidelines - -- **NEVER modify automatically**. always show simplified version first and get approval -- **Preserve technical accuracy**. don't oversimplify to the point of incorrectness -- **Keep code unchanged**. only simplify prose, not code snippets or examples -- **Maintain original meaning**. clarify, don't change intent or facts -- **Don't remove necessary technical terms**. if a term is required, define it instead - -## What NOT to Simplify - -1. **Code snippets or examples**. Leave code as-is -2. **API endpoint names**. Don't change technical identifiers -3. **Product names**. Proper nouns stay the same -4. **Quotes or references**. Don't modify quoted content -5. **Already-simple content**. If it's 8th grade or below, leave it -6. **URLs or file paths**. Technical paths must stay exact -7. **Version numbers**. Don't change technical specifications - -## Edge Cases - -### Already simple content -If content already meets readability standards: -``` -This content already meets the 8th-grade reading level standard. The average sentence length is 15 words, and there's no passive voice or excessive jargon. No simplification needed. -``` - -### Highly technical content -If content must stay technical: -- Simplify the surrounding explanation -- Define technical terms clearly -- Add examples or analogies -- Don't sacrifice accuracy - -Example: -``` -Before: "The OAuth 2.0 authorization framework leverages bearer tokens." -After: "The OAuth 2.0 authorization framework uses bearer tokens (credentials that grant access without additional verification)." -``` - -### Lists and tables -Focus on descriptive text, not list items: -- Simplify list introductions -- Clarify bullet descriptions -- Don't change list structure - -### Short content (1-2 sentences) -May already be optimal: -- Check reading level -- Fix passive voice if present -- Remove filler only -- Don't over-engineer - -## Tips for Good Simplification - -1. **Read aloud**. If it sounds stiff or confusing, simplify more -2. **One idea per sentence**. Don't combine unrelated concepts -3. **Front-load information**. Put the main point first -4. **Use familiar words**. Choose words most people know -5. **Provide examples**. Concrete examples clarify abstract concepts -6. **Test with fresh eyes**. Would a new user understand this? -7. **Maintain voice**. Keep Sumo Logic conversational tone - -## After Simplification - -Suggest: -- Review the rest of the document for similar issues -- Use `/tone-check` to validate voice and tone -- Consider if other sections need simplification -- Test with someone unfamiliar with the topic diff --git a/.claude/commands/tone-check.md b/.claude/commands/tone-check.md deleted file mode 100644 index 3a5c217c08..0000000000 --- a/.claude/commands/tone-check.md +++ /dev/null @@ -1,523 +0,0 @@ -# Tone Check — Sumo Logic Voice and Tone Validation - -Validates documentation against Sumo Logic voice and tone rules, identifying violations and suggesting fixes. - -## What this command does - -When you invoke `/tone-check`, Claude will: - -1. **Fetch style guide**. Get latest voice and tone rules -2. **Read documentation**. Analyze the specified file -3. **Identify violations**. Find voice/tone issues with line numbers -4. **Generate report**. Categorize by severity (Critical, Warning, Suggestion) -5. **Offer fixes**. Show specific corrections -6. **Apply changes**. Update with user approval - -## When to use this command - -* Before submitting a pull request -* After writing new documentation -* Validating existing docs for compliance -* Checking docs flagged in reviews -* Ensuring voice/tone consistency -* Training on Sumo Logic style - -## Workflow - -### Step 1: Fetch Style Guide - -Always fetch before analyzing: -- https://www.sumologic.com/help/docs/contributing/style-guide/ -- https://www.sumologic.com/help/docs/contributing/word-list/ - -These are the authoritative sources for voice and tone rules. - -### Step 2: Get the File - -Ask user which file to check if not specified: -- **Full path**: `/Users/kpohas/sumologic-documentation/docs/integrations/amazon-aws/cloudtrail.md` -- **Relative path**: `docs/integrations/amazon-aws/cloudtrail.md` -- **Filename**: `cloudtrail.md` (search for it) - -### Step 3: Analyze Voice and Tone - -Check for specific violations in order of severity: - -## Critical Issues (Must Fix) - -These MUST be fixed before merging. - -### Wrong Pronouns - -❌ **Violations:** -- "the user can configure" -- "users should navigate" -- "one can access" -- "customers will receive" - -✅ **Correct:** -- "you can configure" -- "you should navigate" or "Navigate" -- "you can access" -- "you'll receive" - -**Why it matters:** Directly addressing the reader as "you" is conversational and engaging. Third-person references ("the user", "one") create distance and feel institutional. - -### Negative Contractions - -❌ **Violations:** -- can't → **cannot** -- won't → **will not** -- don't → **do not** -- isn't → **is not** -- aren't → **are not** -- wasn't → **was not** -- weren't → **were not** -- hasn't → **has not** -- haven't → **have not** -- didn't → **did not** -- doesn't → **does not** -- shouldn't → **should not** -- wouldn't → **would not** -- couldn't → **could not** - -✅ **Correct:** Always spell out negative contractions - -**Why it matters:** This is a firm Sumo Logic style rule. Negative contractions must always be spelled out, even in conversational tone. - -**Positive contractions are OK:** -- you'll, they're, we're, it's, you've, we've - -### Incorrect Branding - -❌ **Violations:** -- "Sumo" (in prose, not code) -- App doc without proper opener -- Source doc without proper opener - -✅ **Correct:** -- "Sumo Logic" or "we" -- App docs: "The Sumo Logic app for [Vendor]..." -- Source docs: "The Sumo Logic source for [Vendor]..." - -**Why it matters:** Consistent branding and proper document openers establish authority and professionalism. - -## Warnings (Should Fix) - -These should be fixed but won't block merging. - -### Passive Voice - -Passive voice is wordy and less direct. - -❌ **Passive examples:** -- "Data is ingested by Sumo Logic" -- "The dashboard can be configured by users" -- "Logs are parsed and indexed" -- "Alerts are triggered when thresholds are exceeded" -- "The source can be set up in minutes" - -✅ **Active alternatives:** -- "Sumo Logic ingests data" -- "You can configure the dashboard" -- "Sumo Logic parses and indexes logs" -- "Sumo Logic triggers alerts when thresholds are exceeded" -- "You can set up the source in minutes" - -**How to identify:** -- Look for "is/are/was/were + past participle" -- Look for "by [actor]" phrases -- Ask: "Who/what is doing the action?" - -**When passive is OK:** -- When the actor is unknown or unimportant -- In technical specifications -- In rare cases for emphasis - -### "Please" in Directives - -Don't use "please" in task instructions. - -❌ **Violations:** -- "Please configure the source" -- "Please click **Save**" -- "Please refer to the documentation" -- "Please note that..." - -✅ **Correct:** -- "Configure the source" -- "Click **Save**" -- "Learn more in the documentation" or "See [link]" -- "Note that..." or just state the fact - -**Why it matters:** Instructional directives should be clear and confident, not apologetic. "Please" makes them sound tentative. - -### "Must" Instead of "Need To" - -Prefer "need to" over "must" for a friendlier tone. - -❌ **Violations:** -- "You must configure authentication" -- "Users must have admin access" -- "You must restart the service" - -✅ **Correct:** -- "You need to configure authentication" -- "You need admin access" -- "You need to restart the service" - -**Exception:** "Must" is OK for hard requirements in technical specifications or legal compliance. - -### Filler Adjectives - -Remove words that add no meaning. - -❌ **Common fillers:** -- **very** (very important, very useful) -- **simply** (simply click, simply add) -- **just** (just navigate, just enter) -- **easy** (easy to use, easy to configure) -- **straightforward** (straightforward process) -- **quickly** (quickly set up) — unless specific time is meant -- **easily** (easily configure) -- **basic** (basic setup) — unless contrasting with advanced - -✅ **Correct:** -- "important" (not "very important") -- "click" (not "simply click") -- "navigate" (not "just navigate") -- "configure" (not "easy to configure") -- Remove or rewrite without filler - -**Why it matters:** Filler words dilute meaning and make content less confident. They often telegraph that something is harder than claimed. - -## Suggestions (Nice to Have) - -These improve quality but are lower priority. - -### Overly Formal Language - -Replace stiff, institutional language with conversational alternatives. - -❌ **Formal:** -- utilize → **use** -- in order to → **to** -- due to the fact that → **because** -- at this point in time → **now** -- in the event that → **if** -- prior to → **before** -- subsequent to → **after** -- commence → **start, begin** -- terminate → **end, stop** -- ascertain → **find out, determine** -- facilitate → **help, enable** -- leverage → **use** - -✅ **Conversational:** Use simpler alternatives - -### Uncommon Contractions - -Avoid contractions that sound awkward when read aloud. - -❌ **Uncommon:** -- should've -- it'll -- they'd -- you'd -- there'd - -✅ **Alternatives:** -- "should have" or rewrite -- "it will" or rewrite -- "they would" or rewrite -- "you would" or rewrite -- "there would" or rewrite - -**Common contractions are OK:** -- you'll, they're, we're, it's, you've, we've, that's, here's - -### Regional Idioms - -Avoid phrases that may not translate well. - -❌ **Regional idioms:** -- "hit the ground running" -- "low-hanging fruit" -- "ballpark figure" -- "touch base" -- "circle back" -- "boil the ocean" - -✅ **Clear alternatives:** -- "start quickly" -- "quick wins" or "easy improvements" -- "rough estimate" -- "check in" or "follow up" -- "revisit this" -- "attempt too much" - -### Step 4: Generate Report - -Format the report with severity levels: - -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Date**: March 23, 2026 -**Status**: ⚠️ 12 issues found - -## Summary -- 3 Critical issues (must fix) -- 6 Warnings (should fix) -- 3 Suggestions (nice to have) - ---- - -## Critical Issues (Must Fix) - -### Wrong Pronouns (2 instances) - -**Line 45:** -``` -the user can configure the source -``` -→ Should be: `you can configure the source` - -**Line 67:** -``` -Users should navigate to the Collection page -``` -→ Should be: `You should navigate to the Collection page` or `Navigate to the Collection page` - ---- - -### Negative Contractions (1 instance) - -**Line 89:** -``` -The field can't be modified after creation -``` -→ Should be: `The field cannot be modified after creation` - ---- - -## Warnings (Should Fix) - -### Passive Voice (4 instances) - -**Line 23:** -``` -Data is collected by the Collector -``` -→ Should be: `The Collector collects data` - -**Line 34:** -``` -Logs are parsed and indexed by Sumo Logic -``` -→ Should be: `Sumo Logic parses and indexes logs` - -**Line 56:** -``` -The dashboard can be customized by users -``` -→ Should be: `You can customize the dashboard` - -**Line 78:** -``` -Alerts are triggered when thresholds are exceeded -``` -→ Should be: `Sumo Logic triggers alerts when thresholds are exceeded` - ---- - -### "Please" in Directives (2 instances) - -**Line 12:** -``` -Please click **Save** to apply changes. -``` -→ Should be: `Click **Save** to apply changes.` - -**Line 91:** -``` -Please refer to the troubleshooting guide for help. -``` -→ Should be: `See the troubleshooting guide for help.` or `Learn more in the troubleshooting guide.` - ---- - -## Suggestions (Nice to Have) - -### Filler Words (3 instances) - -**Line 15:** -``` -Simply click the **Add** button to begin. -``` -→ Should be: `Click the **Add** button to begin.` - -**Line 42:** -``` -This feature is very important for security. -``` -→ Should be: `This feature is important for security.` - -**Line 73:** -``` -The source is easy to configure in just a few steps. -``` -→ Should be: `Configure the source in a few steps.` or `You can configure the source in a few steps.` - ---- - -## Next Steps - -Would you like me to: -1. **Auto-fix all issues**. Apply all corrections automatically -2. **Fix critical issues only**. Just fix the must-have items -3. **Show specific fixes**. Let me walk through each fix -4. **Generate checklist**. Create a manual review checklist -5. **Export report**. Save this report as a markdown file -``` - -### Step 5: Offer Fixes - -After presenting the report, ask what the user wants to do: - -**Option 1: Auto-fix all** -- Apply all corrections using Edit tool -- Show summary of changes made -- Re-run tone check to verify - -**Option 2: Fix by severity** -- Critical only -- Critical + warnings -- Custom selection - -**Option 3: Manual review** -- User fixes themselves -- Provide checklist -- Available for questions - -## Safety Guidelines - -- **NEVER modify automatically without asking**. always present report first -- **Provide context**. explain WHY something violates tone rules, not just WHAT -- **Show specific fixes**. don't just flag issues, suggest corrections with line numbers -- **Preserve technical accuracy**. tone fixes should not change meaning -- **Respect user decisions**. if they decline a fix, respect that choice - -## What NOT to Flag - -1. **Code blocks**. Don't check voice/tone in code snippets -2. **Quoted content**. Don't flag violations in quotations -3. **Product names**. Don't flag "Sumo" in product names like "Sumo App" -4. **URLs and paths**. Don't check tone in technical identifiers -5. **Examples of wrong usage**. Don't flag intentionally incorrect examples -6. **Comments or notes**. May use different tone - -## Edge Cases - -### No Issues Found - -If content passes all checks: -```markdown -# Tone Check Report -**File**: docs/integrations/amazon-aws/cloudtrail.md -**Status**: ✅ All checks passed - -This document meets all Sumo Logic voice and tone standards: -- No pronoun violations -- No negative contractions -- No passive voice -- No "please" in directives -- No filler words -- Proper branding - -Great work! -``` - -### Too Many Issues - -If there are 20+ violations: -```markdown -# Tone Check Report -**Status**: ⚠️ 47 issues found - -This document has significant voice and tone issues. I recommend: - -1. Start with critical issues (12 found) -2. Review patterns (passive voice appears 23 times) -3. Consider rewriting sections instead of fixing individually -4. Use /rewrite-intro for the opening -5. Use /simplify for complex sections - -Would you like me to: -- Fix all critical issues first? -- Rewrite the most problematic sections? -- Provide a training overview of the main issues? -``` - -### Mixed Content Types - -Different sections may have different standards: -- **Prose**: Apply all voice/tone rules -- **Code**: Skip tone checks -- **Examples**: Check explanatory text, not examples themselves -- **Quotes**: Don't check quoted content -- **Technical specs**: More lenient on passive voice - -### Document-Specific Exceptions - -Some documents may have valid exceptions: -- **API reference**: May use passive voice for specifications -- **Release notes**: May use past tense and passive voice -- **Legal/compliance**: May need formal language -- **Migration guides**: May reference "users" when describing old vs. new behavior - -Flag these as suggestions, not critical issues. - -## After the Tone Check - -Suggest next steps: -- If many issues: Use `/rewrite-intro` or `/simplify` on problematic sections -- If clean: Ready for PR -- If medium issues: Fix and re-run tone check -- Consider running `/audit-doc` for full quality check - -## Common Patterns - -### Serial Offenders - -**Passive voice throughout:** -``` -Recommend: "I found 15 instances of passive voice. Would you like me to convert them all to active voice?" -``` - -**Wrong pronouns everywhere:** -``` -Recommend: "The document consistently uses 'users' instead of 'you'. Let me update all 12 instances." -``` - -**Filler word addiction:** -``` -Recommend: "'Simply' appears 8 times and 'just' appears 11 times. These can all be removed." -``` - -### One-Off Violations - -For 1-2 violations, just fix them: -``` -"Found one negative contraction on line 45. Should I fix it?" -``` - -## Tips for Running Tone Checks - -1. **Run early and often**. Catch issues before they multiply -2. **Check before PRs**. Don't let violations reach review -3. **Use with /simplify**. Tone check after simplifying content -4. **Train your eye**. Learn common patterns to avoid them -5. **Focus on critical first**. Don't get bogged down in suggestions -6. **Batch similar fixes**. Fix all passive voice at once -7. **Re-run after fixes**. Verify all issues resolved diff --git a/CLAUDE.md b/CLAUDE.md index 7850dc2904..108e0aed61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,24 @@ Docs live in /docs, written in Markdown. Contributions follow the Sumo Logic sty - .claude/skills/pr-template-guide/SKILL.md — PR template structure, formatting examples, and best practices. - .claude/skills/geo-guide/SKILL.md — Reference guide of GEO principles and patterns loaded as context by `/geo-optimize` and `/seo-audit`. Not an invocable command. +## Bulk Changes +For any change touching 50+ files (e.g. terminology migrations, frontmatter audits, link updates, admonition format changes), follow these rules: + +**Enter plan mode** (`/plan`) at the start of any bulk change. Present scope, file count, directory breakdown, and before/after samples — then wait for explicit approval before touching any files. + +1. **Define scope first, get sign-off.** State the exact pattern, included paths, excluded paths, and known edge cases before touching files. +2. **Dry-run before writing.** Report total file count, per-directory breakdown, and ~10 before/after samples. Wait for confirmation. +3. **Apply in batches by directory**, not all at once. Show `git diff --stat` and a few spot-checks after each batch. +4. **One commit per batch/category** — never bundle multiple directories into one commit. Atomic commits stay revertable. +5. **Never revert from memory.** If reverting, validate against actual file content — do not trust "the original had X." +6. **Never commit helper/detection scripts** to the repo. Run them ephemerally. + +## Doc Reviews + +When reviewing any PR or doc, always check existing docs of the same type in the same directory before flagging issues. A pattern consistent with neighboring docs is not a bug — it is the established convention. Only flag it if it's a deviation from the pattern or a net-new problem introduced by the PR. + +Some directories have conventions that differ significantly from standard docs. For example, `docs/platform-services/automation-service/app-central/integrations/` intentionally uses `description: ''`, omits `id`, opens with a logo image, and includes a `***Version / Updated***` block — all correct for that directory. When in doubt, read two or three neighboring files before forming an opinion. + ## Pull Requests **CRITICAL REQUIREMENT**: Before creating ANY PR, MUST read `.github/PULL_REQUEST_TEMPLATE.md` and use EXACT checkbox labels from that file. @@ -32,6 +50,8 @@ See `.claude/skills/pr-template-guide/SKILL.md` for examples and guidance. ## Git Rules **CRITICAL**: Never commit, merge, or push changes without explicit user approval — even if "accept edits" is enabled. Always ask first. +**Branch naming**: Branch names must always be the Jira ticket number only (e.g., `DOCS-1697`). No additional description. + Before merging any PR, provide the user with the commit description and wait for explicit approval. Before pushing any commit that changes docs content: @@ -73,7 +93,7 @@ Primary commands for documentation work. Proactively suggest when context fits **Content:** `/doc`, `/doc-from-jira`, `/app-doc`, `/c2c-source-doc`, `/remove-doc` **Release notes:** `/release-note-service`, `/release-note-collector`, `/release-note-cse`, `/release-note-csoar`, `/release-note-developer` -**Quality:** `/audit-doc`, `/seo-audit`, `/geo-optimize`, `/tone-check`, `/rewrite-intro`, `/simplify` +**Quality:** `/audit-doc`, `/seo-audit`, `/geo-optimize` **Workflow:** `/jira`, `/review` **When to proactively suggest:** @@ -82,9 +102,59 @@ Primary commands for documentation work. Proactively suggest when context fits - Doc needs discoverability improvements → suggest `/geo-optimize` - User asks about doc quality → suggest `/audit-doc` and `/seo-audit` together -**Key distinctions:** -- `/jira` = manage tickets | `/doc-from-jira` = scaffold doc from ticket -- `/audit-doc` = structure/style/links | `/seo-audit` = discoverability signals (run both before PRs) +### Slash commands + +**Creating docs** + +| Command | What it does | +|---------|-------------| +| `/doc` | Create a new feature, how-to, concept, reference, or troubleshooting doc | +| `/doc-from-jira` | Fetch a DOCS Jira ticket and scaffold a complete doc from it | +| `/app-doc` | Create a new app integration doc | +| `/c2c-source-doc` | Create a new Cloud-to-Cloud source integration doc | + +**Release notes** + +| Command | What it does | +|---------|-------------| +| `/release-note-service` | New service release note | +| `/release-note-collector` | New Collector release note | +| `/release-note-cse` | New Cloud SIEM release note | +| `/release-note-csoar` | New Cloud SOAR release note | +| `/release-note-developer` | New developer/API release note | + +**Editing and reviewing** + +| Command | What it does | +|---------|-------------| +| `/audit-doc` | Full quality audit: structure, style, links, frontmatter, completeness | +| `/seo-audit` | Discoverability audit: SEO, AEO, and GEO signals — run this before a PR | +| `/geo-optimize` | Rewrite a doc to improve AI citation and generative engine visibility | + +**Jira** + +| Command | What it does | +|---------|-------------| +| `/jira` | Create, update, search, or transition DOCS Jira tickets | +| `/doc-from-jira` | Start a new doc from a Jira ticket (use this instead of `/jira` when the goal is to write a doc) | + +**Removing docs** + +| Command | What it does | +|---------|-------------| +| `/remove-doc` | Safely deprecate or move a doc with redirects | + +### Which audit command to use + +Run both for a thorough pre-PR check — they cover different things: + +- **`/audit-doc`** — structure, required sections, broken links, frontmatter completeness, style guide +- **`/seo-audit`** — SEO/AEO/GEO signals: title length, description quality, question headings, direct answers, GEO patterns + +### `/jira` vs `/doc-from-jira` + +- Use **`/jira`** to manage tickets: create, search, update fields, change status, view your queue +- Use **`/doc-from-jira`** when you have a ticket and want to start writing the doc it describes — it fetches the ticket and scaffolds the file ## Commands