elastic / elastic/docs-actions

Align PR Review Action Guidance with Agreed Style Recommendations

Open
#288 0 comments 0 reactions 0 assignees View on GitHub
automation
Dominant language
Python
Stars
5
Forks
9
Avg merge
1d 21h
Merged PRs (30d)
30

Description

Context: Recent Slack thread highlights inconsistency between the docs review action guidance and the established style guide regarding recommendations and modal verbs (should/we recommend).

Task:
- Update the PR review action logic and messages to clearly align with the Slack consensus:
- Prefer active, second-person, and imperative tone for recommendations where there is a single best approach.
- "We recommend" should be tolerated only sparingly and never as a mandate; only use when no clearer, user-focused phrasing is possible.
- Avoid "should/could/would", passive voice, and ambiguous advice.
- Document references and link to the style guide sections for rationale.
- Example thread for context: contributors have found previous review bot suggestions confusing and not in sync with https://www.elastic.co/docs/contribute-docs/style-guide/voice-tone#avoid-ambiguity and https://www.elastic.co/docs/contribute-docs/style-guide/grammar-spelling#verb-tense

Goal: Reduce contributor confusion by ensuring the PR review automation and style guide messaging are in sync.

/cc Doc team for review and input.

[View original Slack conversation](https://elastic.slack.com/archives/C05PP2LEC1X/p1786701623644429?thread_ts=1786701623.644429&cid=C05PP2LEC1X)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the PR review action logic and its recommendation messages, then compare them with the linked style guide sections on ambiguity and verb tense. Update the guidance so the stated tone and modal-verb rules are consistent, and add or adjust references and tests as needed to verify the messages.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Refactor
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.