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. |
.claude/rules/quality-standards.md
Outdated
| - [ ] All links use descriptive text (avoid "click here") | ||
| - [ ] Images include meaningful alt text | ||
| - [ ] Content uses inclusive language and active voice | ||
| - [ ] Headings follow proper hierarchy (H1 → H2 → H3) |
There was a problem hiding this comment.
quick note here, that is not actual how we should do it. In frontmatter we use title that docusaurus automatically uses as H1 if there is hard-coded H1 (and usually there is not) it makes for easier maintenance. Not sure if we can make Claude infer that title key in frontmatter = H1 after transformation from .md to HTML
There was a problem hiding this comment.
I'm not sure I follow. This is just a copy of the previous cursor rule that's been recreated as MD and then symlinked back to MDC for compatibility.
Are you saying that we need to update the original rule or that there's something wrong with the file now?
There was a problem hiding this comment.
I'm sorry, sleep deprivation may have gotten the best of me on that one. Let me clarify. The rule itself is fine, I'm suggesting we clarify the wording to avoid confusion.
Current wording implies authors should write H1s manually:
- Heading hierarchy is correct (H1 → H2 → H3, no skipped levels)
But in Docusaurus, the title front matter key generates the H1 automatically. Authors should never write a manual # Heading - they start at H2.
Perhaps a rewording to something like:
- Heading hierarchy is correct (H2 → H3 → H4, no skipped levels; H1 comes from front matter title)
This helps LLM s(and human contributors) understand they shouldn't add manual H1s while still enforcing proper hierarchy.
Does that make sense?
|
Just a quick side note won't this interfere with #2193 ? |
.claude/rules/quality-standards.md
Outdated
| - [ ] All links use descriptive text (avoid "click here") | ||
| - [ ] Images include meaningful alt text | ||
| - [ ] Content uses inclusive language and active voice | ||
| - [ ] Headings follow proper hierarchy (H1 → H2 → H3) |
There was a problem hiding this comment.
I'm not sure I follow. This is just a copy of the previous cursor rule that's been recreated as MD and then symlinked back to MDC for compatibility.
Are you saying that we need to update the original rule or that there's something wrong with the file now?
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>
|
Preview for this PR was built for commit |
Add comprehensive Claude Code configuration for the Apify documentation repository: - Main instructions.md with project overview, standards, and workflows - Four specialized skills: doc-write, api-doc, tutorial, and review-docs - Configuration file (claude.json) registering skills and context files - User guide (README.md) with quick start and usage examples - Setup summary documenting the complete infrastructure All skills based on existing AGENTS.md and CONTRIBUTING.md standards to ensure consistency across documentation. Includes templates, examples, quality checklists, and best practices for common documentation tasks. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Update all Claude Code instructions and skills to include important details
from personal instruction file:
Critical additions:
- Bold ONLY for UI elements, NEVER for emphasis (emphasized throughout)
- All admonitions MUST have titles (no exceptions)
- Apify-specific terminology section with exact capitalization rules
- Oxford comma requirement
- Simple present tense for headings (not gerunds)
- "Never make assumptions about product features"
- Front matter descriptions must explain value, not features
- Slug must match file path
- Simple English preference ("use" not "utilize")
- PR review process (check latest changes pulled first)
- Code review scope (comments and obvious mistakes only)
Updated files:
- instructions.md: Core standards with terminology and review process
- review-docs.md: Enhanced checklist with terminology verification
- doc-write.md: Added terminology section and updated checklist
- tutorial.md: Added terminology and formatting rules
- api-doc.md: Added terminology for API descriptions
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Change H1 headings to H2 in all .claude files per Apify.H1 rule - Add blank lines around headings, lists, and code blocks in README.md - Add language specifications to code blocks in README.md - Update tutorial template to use H2 instead of H1 - Adjust Python comment formatting to avoid vale false positives Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Fix last vale error by consolidating Python comments in tutorial.md - Remove SETUP_SUMMARY.md as it duplicates README.md content Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add blank lines around all headings, lists, and code blocks - Ensures MD022, MD032, and MD031 rules are satisfied Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Change H2 back to H1 for first line (MD041 requirement) - Add blank lines around all headings, lists, and code blocks - These .claude files are infrastructure, not published docs Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add .claude/**/*.md to vale.ini H1 exception (infrastructure docs like README) - Fix blank lines around headings, lists, and code blocks in all skill files - Add language specs to code blocks where possible - Add linting commands to instructions.md for local validation - 4 remaining MD040/MD001 errors are false positives from nested code examples Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Close markdown code block in review-docs.md properly - Reduces linting errors to 5 false positives from nested examples Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add .claude to .markdownlintignore (infrastructure docs) - Configure vale to skip all checks for .claude/**/*.md files - These files are Claude Code configuration, not published documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
Remove duplicate content and improve organization across Claude Code documentation: - instructions.md: Remove duplicated sections (API specifics, common patterns, quality checklist), replace with references to skills - README.md: Simplify skill descriptions from verbose multi-line to concise one-liners - review-docs.md: Reorganize 11-item checklist into 3 categories (writing quality, content formatting, technical validation) - writing-style.md: Remove terminology section that duplicates terminology.md, add cross-reference Result: 103 lines reduced, better scannability, single source of truth maintained. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add new canonical standards files and update all skills to reference them: New files: - rules/content-standards.md: Formatting, front matter, code examples, links, images - rules/terminology.md: Apify-specific capitalization and word choice Updated files: - rules/quality-standards.md: Complete rewrite with comprehensive checklist by category - skills/api-doc.md: Add standards reference, remove duplicated terminology - skills/doc-write.md: Add standards reference, focus on doc-specific patterns - skills/tutorial.md: Add standards reference, remove duplicated formatting rules Result: All skills now reference centralized standards instead of duplicating rules. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Preview for this PR was built for commit |
…uality and writing style guidelines
|
Preview for this PR was built for commit |
4 participants
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