docs: Add Claude Code writing style guide #2198
Conversation
Add .claude/rules/writing-style.md with documentation writing guidelines for AI assistants. Based on Apify style guide and TC-MO's technical writer feedback from PR #2185. Includes: - Core principles (simple, factual, technical) - Formatting rules (headings, bold, lists) - Grammar guidelines (articles, Oxford comma) - Terminology standards (Actor capitalization, word choice) - Common mistakes to avoid Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
Add missing rules from CONTRIBUTING.md/AGENTS.md and TC-MO review patterns: - Content Types section: Match CTA verbs to content type (tutorials vs reference) - Active & Inclusive Voice: Active voice, gender-neutral, no directional UI language - Bold: Clarify bold IS for UI elements, NOT for structural labels - Italics: Guidance for emphasis and new term introduction - List types: When to use numbered vs bullet lists - Admonitions: Docusaurus admonition types and usage - Accessible links: Avoid "click here", use descriptive text - Navigable tool mentions: Link external tools/resources - Reference section: Point to CONTRIBUTING.md and AGENTS.md for structural guidelines Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
- Fix Vale AM/PM error: use uppercase "5 PM" - Fix MD060: align all table columns properly - Fix MD032: add blank lines around lists - Fix MD059: wrap bad link examples in code backticks Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Ensure all table columns are properly aligned: - Content Types table - Admonitions table - Articles in definitions table - Word choice table - Trim filler words table Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
|
we could also use already existing .cursor rules for this, they go a bit more granular than AGENTS.md and CONTRIBUTING.md |
|
Preview for this PR was built for commit |
I see. I guess that Claude didn't check for cursor rules. We should probably have one set of rules and then symlink it into the other directories for easy discovery by different tools and models. |
|
Good point tbh we started with |
|
I'm having Claude to do the reconciliation and symlinking now. Curious what it will come up with. |
Consolidates documentation rules into a single canonical source in .cursor/rules/writing-style.mdc with Cursor frontmatter. Claude Code reads the same rules via symlink, ensuring both tools stay in sync. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Symlinks additional rule files from .cursor/rules to .claude/rules, keeping both tools in sync for documentation rules. ## Recommendation for TC-MO review Analysis found `quality-standards.mdc` is mostly redundant with `writing-style.mdc` (5 of 8 checklist items are duplicates). Three items in quality-standards are NOT in writing-style: - Front matter requirements - Alt text for images - Heading hierarchy (H1 → H2 → H3) Suggested consolidation: 1. Add missing 3 items to writing-style.mdc 2. Remove quality-standards.mdc (or keep as optional quick-reference) 3. Keep file-organization.mdc separate (different scope) This would give a cleaner split: - writing-style.mdc = how to write content - file-organization.mdc = how to name/organize files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
## Problem Claude Code only reads `.md` files from `.claude/rules/`. Cursor IDE requires `.mdc` extension for rules to be recognized. The previous approach (canonical in .cursor/rules/, symlinks to .claude/) meant Claude Code would never read the rules because they had .mdc extension. ## Solution Reverse the symlink direction: ``` # Canonical files (Claude Code reads .md) .claude/rules/writing-style.md .claude/rules/file-organization.md .claude/rules/quality-standards.md # Symlinks for Cursor (.mdc extension required) .cursor/rules/writing-style.mdc → .claude/rules/writing-style.md .cursor/rules/file-organization.mdc → .claude/rules/file-organization.md .cursor/rules/quality-standards.mdc → .claude/rules/quality-standards.md ``` The YAML frontmatter in .md files is harmless to Claude Code - it just sees it as extra context. Cursor reads the symlinked content and the .mdc extension satisfies its format requirement. ## Result - Single source of truth in .claude/rules/*.md - Both Claude Code and Cursor can read the rules - Future edits happen in one place Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
.claude/rules/ and .cursor/rules/ contain configuration files for AI assistants, not user-facing documentation. These files weren't checked before because .cursor/rules/ used .mdc extension (not in Vale's scope). Now that canonical files are .md in .claude/rules/, they need explicit exclusion since they don't follow documentation conventions (e.g., H1 headings are fine in config files). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
|
@TC-MO I think it's ready for review now. I had Claude write summaries into the commit messages, so you can follow the process. |
Summary
Adds a centralized writing style guide for AI-assisted documentation at
.claude/rules/writing-style.md.What's in the guide:
Context
This is an experiment in extracting writing style patterns at scale using Claude Code.
The process:
Why this matters:
If this approach works, we can continuously improve our style guides by mining reviewer feedback rather than relying on manual documentation efforts. The guide gets better as we review more PRs.
Test plan
🤖 Generated with Claude Code