[Docs] Add a documentation style and grammar guide for contributors and agents#64518
[Docs] Add a documentation style and grammar guide for contributors and agents#64518dstrodtman wants to merge 1 commit into
Conversation
…nd agents Add doc/source/ray-contribute/writing-style.md as the canonical style and grammar standard for the Ray documentation. It covers voice, word choice, sentence structure, headings, lists, links, admonitions, and MyST formatting, and builds on the Google developer documentation style guide as a fallback. Prose guidance was previously thin and scattered: docs.md linked to Google with five highlights, a Cursor rule carried a partial guide, and Claude agents had no prose guidance at all. This establishes a single source of truth and points the agent surfaces at it: - docs.md "Editorial style" now points to the new guide. - getting-involved.md toctree includes the new page. - doc/.cursor/rules/ray-docs-style.mdc slims to a high-frequency subset plus a pointer to the full guide. - doc/.claude/rules/prose-style.md (new) gives Claude agents parity, scoped to doc/source Markdown and rST. This change also touches agent configuration (.cursor and .claude) so both AI agent surfaces reference the same standard. Follow-up, not in this change: Vale currently runs only on doc/source/data and the example gallery. Broadening prose enforcement is a separate, reviewer- sensitive change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive house style guide for Ray documentation (writing-style.md) and updates related configuration files, rules, and documentation to reference it. The reviewer pointed out that a link to the Vale documentation in docs.md should be updated to use the {ref} role instead of standard Markdown link syntax, aligning with the newly established guidelines.
| * [Use sentence case](https://developers.google.com/style/capitalization) | ||
|
|
||
| Vale enforces the editorial style in CI. For more information, see [How to use Vale](vale). | ||
| The house guide builds on the [Google developer documentation style guide](https://developers.google.com/style), which is the fallback for anything the house guide doesn't cover. Vale enforces an automated subset of the Google guide in CI. For more information, see [How to use Vale](vale). |
There was a problem hiding this comment.
The link [How to use Vale](vale) uses standard Markdown link syntax to reference a label (vale)=. According to the new style guide established in this PR, cross-references to labeled targets should use the {ref} role.
| The house guide builds on the [Google developer documentation style guide](https://developers.google.com/style), which is the fallback for anything the house guide doesn't cover. Vale enforces an automated subset of the Google guide in CI. For more information, see [How to use Vale](vale). | |
| The house guide builds on the [Google developer documentation style guide](https://developers.google.com/style), which is the fallback for anything the house guide doesn't cover. Vale enforces an automated subset of the Google guide in CI. For more information, see {ref}`vale`. |
| - Use: "To build the docs, follow these steps:" Not: "Let's build the docs." | ||
| - Use: "The Ray project welcomes contributions of all kinds." Not: "We welcome all contributions." | ||
|
|
||
| ### Capitalize Ray components and product names |
There was a problem hiding this comment.
@richardliaw @edoakes @akshay-anyscale I differ to y'all here, but do prefer lowercase. (Even K8s, which has historically really relied on casing for meaning, seems to be moving away from it in their docs and recent style guides).
There was a problem hiding this comment.
We should use capitalization for product names, except for known exceptions like "pandas"
Why are these changes needed?
The Ray documentation had no single prose style standard. Guidance was thin and scattered across three surfaces that didn't agree:
docs.mdlinked to the Google developer style guide with five highlight bullets.doc/.cursor/rules/ray-docs-style.mdc) carried a partial style guide that had accumulated topic-specific leftovers.This PR establishes a single source of truth and points every surface at it.
New canonical guide.
doc/source/ray-contribute/writing-style.mdcovers voice, word choice, sentence structure, headings, lists, links, admonitions, tables, and MyST formatting, with the Google developer documentation style guide as the fallback for anything it doesn't cover. It's written for both human contributors and AI coding agents.Wiring:
docs.md"Editorial style" now points to the new guide.getting-involved.mdtoctree includes the new page.doc/.cursor/rules/ray-docs-style.mdcslims to a high-frequency subset plus a pointer to the full guide.doc/.claude/rules/prose-style.md(new) gives Claude Code agents parity with Cursor, scoped todoc/sourceMarkdown and rST.Note on scope: this PR touches AI agent configuration (
.cursorand.claude) so that both agent surfaces reference the same standard as the published guide.Not in this PR: Vale runs in CI only on
doc/source/dataand the example gallery. Broadening prose enforcement is a separate, reviewer-sensitive change.Related issue number
None.
Checks
git commit -s) to meet the DCO requirement.fail_on_warning) is the gate for cross-references and toctree wiring.🤖 Generated with Claude Code