Skip to content

[Docs] Add a documentation style and grammar guide for contributors and agents#64518

Open
dstrodtman wants to merge 1 commit into
ray-project:masterfrom
dstrodtman:djs-260702-docs-writing-style-guide
Open

[Docs] Add a documentation style and grammar guide for contributors and agents#64518
dstrodtman wants to merge 1 commit into
ray-project:masterfrom
dstrodtman:djs-260702-docs-writing-style-guide

Conversation

@dstrodtman

Copy link
Copy Markdown
Contributor

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.md linked to the Google developer style guide with five highlight bullets.
  • A Cursor rule (doc/.cursor/rules/ray-docs-style.mdc) carried a partial style guide that had accumulated topic-specific leftovers.
  • AI coding agents using Claude Code had no prose guidance at all.

This PR establishes a single source of truth and points every surface at it.

New canonical guide. doc/source/ray-contribute/writing-style.md covers 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.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 Code agents parity with Cursor, scoped to doc/source Markdown and rST.

Note on scope: this PR touches AI agent configuration (.cursor and .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/data and the example gallery. Broadening prose enforcement is a separate, reviewer-sensitive change.

Related issue number

None.

Checks

  • I've signed off every commit (git commit -s) to meet the DCO requirement.
  • I've made sure the tests are passing. This is a docs-only change; the Read the Docs build validates it.
  • Testing strategy: the Read the Docs build (fail_on_warning) is the gate for cross-references and toctree wiring.

🤖 Generated with Claude Code

…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>
@dstrodtman dstrodtman requested review from a team as code owners July 2, 2026 19:32

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should use capitalization for product names, except for known exceptions like "pandas"

@ray-gardener ray-gardener Bot added the core Issues that should be addressed in Ray Core label Jul 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core Issues that should be addressed in Ray Core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants