elastic / elastic/docs-actions
Align PR Review Action Guidance with Agreed Style Recommendations
- 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