[GH-ISSUE #4353] [Docs] #1724

New issue

Open

opened 2026-10-16 21:09:30 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-16 21:09:30 +00:00

Owner

Originally created by @webxiu on GitHub (Oct 16, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/4353

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

anypage.md, installation.md

Problem

The documentation is poorly written—I really have to wonder what’s wrong with these authors! For instance, if you ask for a guide on the cooking process, they might start off by talking about how to add salt, techniques for chopping vegetables, or how to turn on the gas stove... They even go so far as to categorize these points, for example:

Adding salt to your food makes it delicious; it not only enhances flavor but also helps prevent goiters—very useful!
When it comes to chopping vegetables, you should choose a high-quality kitchen knife—after all, even the most skilled martial artist is no match for a sharp blade! Think of it as your safety assistant.
Turning on the gas is a crucial step—an essential part of the cooking process—as it enables the rapid transformation of raw ingredients into cooked food.
...
While these points might seem tangentially related to cooking, they certainly don’t describe the actual cooking process.

Expected content

Speak in plain language.

Supporting evidence

none

Additional context

none

Originally created by @webxiu on GitHub (Oct 16, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/4353 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location anypage.md, installation.md ### Problem The documentation is poorly written—I really have to wonder what’s wrong with these authors! For instance, if you ask for a guide on the cooking process, they might start off by talking about how to add salt, techniques for chopping vegetables, or how to turn on the gas stove... They even go so far as to categorize these points, for example: 1. Adding salt to your food makes it delicious; it not only enhances flavor but also helps prevent goiters—very useful! 2. When it comes to chopping vegetables, you should choose a high-quality kitchen knife—after all, even the most skilled martial artist is no match for a sharp blade! Think of it as your safety assistant. 3. Turning on the gas is a crucial step—an essential part of the cooking process—as it enables the rapid transformation of raw ingredients into cooked food. ... While these points might seem tangentially related to cooking, they certainly don’t describe the actual cooking process. ### Expected content Speak in plain language. ### Supporting evidence none ### Additional context none

bsakaguchi added the

triage

documentation

labels

2026-10-16 21:09:30 +00:00

bsakaguchi commented

2026-10-31 00:32:21 +00:00

Author

Owner

@morluto commented on GitHub (Oct 26, 2026):

Thank you for the feedback about making the guides more direct. Could you point to one or two specific pages and passages where the steps are hard to follow, and say what you were trying to accomplish? That would help us improve the relevant workflow without losing useful setup details. The report remains open for those examples.

@morluto commented on GitHub (Oct 26, 2026): Thank you for the feedback about making the guides more direct. Could you point to one or two specific pages and passages where the steps are hard to follow, and say what you were trying to accomplish? That would help us improve the relevant workflow without losing useful setup details. The report remains open for those examples.

bsakaguchi referenced this issue

2026-10-31 00:38:34 +00:00

[GH-ISSUE #5396] [Bug] Duplicate record_unknown calls are reported as retryable revision conflicts #3266

bsakaguchi referenced this issue

2026-10-31 00:43:31 +00:00

[GH-ISSUE #6106] [Bug] Residual-unknown input validation is reported as changed Evidence state #3738

bsakaguchi referenced this issue

2026-10-31 00:55:00 +00:00

[PR #1733] [MERGED] fix(evidence): normalize unknown revisions and preserve mutation intent #4783