RFC 0027: Simplified Technical English for OpenClaw documentation - #53
Draft
jjjhenriksen wants to merge 3 commits into
Draft
RFC 0027: Simplified Technical English for OpenClaw documentation#53jjjhenriksen wants to merge 3 commits into
jjjhenriksen wants to merge 3 commits into
Conversation
clawsweeper
Bot
added
rating: 🦐 gold shrimp
|
Codex review: needs real behavior proof before merge. Reviewed August 15, 2026, 3:05 AM ET / 07:05 UTC. ClawSweeper reviewWhat this changesThis draft adds an RFC proposing Simplified Technical English, a shared terminology base, and phased documentation-review policy across OpenClaw repositories. Merge readiness⛔ Blocked by patch quality or review findings - 8 items remain Keep open for maintainer product-direction review, but the current branch has a blocking RFC identifier collision that must be resolved first. Priority: P2 Review scores
Verification
How this fits togetherThe RFC repository records cross-project design proposals that later guide documentation and contributor workflows. This proposal would turn author-written documentation into shared writing guidance, terminology, and later review-policy decisions. flowchart LR
A[Documentation authors] --> B[RFC proposal]
B --> C[Writing standard]
C --> D[Term base and guidance]
D --> E[Human review]
E --> F[Repository documentation]
Decision needed
Why: The RFC creates a documentation policy and proposes eventual enforcement beyond this repository; source review cannot determine the desired organization-wide scope or operating ownership. Before merge
Findings
Agent review detailsSecurityNone. Review metrics
Merge-risk optionsMaintainer options:
Technical reviewBest possible solution: Reserve a unique RFC number, then use the maintainer discussion to decide whether to adopt STE as guidance first and defer any required cross-repository enforcement to a later, separately approved proposal. Do we have a high-confidence way to reproduce the issue? Not applicable: this RFC proposes documentation policy rather than reporting a runtime failure. Is this the best way to solve the issue? No: the proposal needs a unique RFC identity before it can be reviewed as a landing candidate, and its future enforcement path requires maintainer direction. Full review comments:
Overall correctness: patch is incorrect AGENTS.md: not found in the target repository. Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f. LabelsLabel changes:
Label justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (69 earlier review cycles; latest 8 shown)
|
clawsweeper
Bot
added
rating: 🐚 platinum hermit
clawsweeper
Bot
added
rating: 🦪 silver shellfish
clawsweeper
Bot
added
merge-risk: 🚨 other
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Problem This Solves
OpenClaw technical documentation spans many repositories and document types.
Different terms and sentence structures make technical meaning, search, and
translation less reliable. Contributors also lack one shared process for
reviewing new prose and for recording when a code change needs documentation.
Why This Change Was Made
RFC 0027 defines ASD-STE100 Issue 9 as the English technical-writing standard,
adds an OpenClaw term base, and proposes small repository-owned migration sets.
It also defines source and generated-document boundaries, an author-aid
checker, dual human review, phased rollout, and migration evidence.
The rollout is intentionally slow. It gives contributors and AI-assisted
contributors a short guide and examples first. It then proposes staged
ClawSweeper reporting, followed by a required check for PRs that change
documentation or change behavior that needs a documentation decision.
User Impact
This proposal aims to make OpenClaw documentation clearer, more consistent,
and easier to translate. It does not change code, runtime behavior, CLI help,
UI text, commands, API values, or generated translation output. The current
PR is an RFC-only draft; implementation and any ClawSweeper gate require later
maintainer review.
Evidence
git diff --checkrfcs/0000-template.mdandREADME.mdmainreview and comparison with merged RFC PRs, including the repository PR template alignment in chore: align pull request template #36openclaw/openclawtoopenclaw/docspublication and translation boundary preservedAI-assisted draft; wording and rollout boundaries reviewed manually.