|
| 1 | +# Technical blog review guideline |
| 2 | + |
| 3 | +Use this rubric when a pull-request comment requests a **technical blog** or |
| 4 | +**technical announcement** review. It applies to public-facing documentation |
| 5 | +such as `docs/source/announcements/` and complements the repository's normal |
| 6 | +code-review guidance. |
| 7 | + |
| 8 | +## Review scope |
| 9 | + |
| 10 | +Review the changed announcement and its landing-page card together. Do not |
| 11 | +review unrelated source files unless they provide evidence for a claim in the |
| 12 | +post. |
| 13 | + |
| 14 | +## Checks |
| 15 | + |
| 16 | +1. **Factual support** — Every technical claim, performance number, and |
| 17 | + comparison must be supported by a cited public source, a clearly identified |
| 18 | + reproducible measurement, or a qualified statement. Flag claims that |
| 19 | + overstate what the cited source establishes. |
| 20 | +2. **Citation integrity** — Check that cited papers, repositories, checkpoints, |
| 21 | + and issue or PR links exist and match the surrounding claim. Publication |
| 22 | + dates must not precede the cited source's availability. |
| 23 | +3. **Technical precision** — Preserve meaningful distinctions: measured versus |
| 24 | + inferred results, training versus serving behavior, throughput versus |
| 25 | + latency, architecture versus implementation detail, and public facts versus |
| 26 | + internal context. |
| 27 | +4. **Figure provenance** — Images need an accurate alt text and a source or |
| 28 | + provenance that makes their public use appropriate. Captions and nearby |
| 29 | + text must not imply a result the figure does not show. |
| 30 | +5. **Public-release suitability** — Do not expose private infrastructure, |
| 31 | + unreleased products, confidential benchmark data, credentials, internal |
| 32 | + URLs, or claims that cannot be independently supported by public material. |
| 33 | +6. **Reader clarity** — Verify the title, date, author, summary, tags, and |
| 34 | + announcement-card metadata agree. Prefer precise terminology over marketing |
| 35 | + shorthand when the two could be confused. |
| 36 | + |
| 37 | +## Findings |
| 38 | + |
| 39 | +Raise only material findings. Each finding should identify the exact claim, |
| 40 | +explain the public-facing risk, and propose a concrete correction. Do not |
| 41 | +duplicate routine style, spelling, or formatting feedback already handled by |
| 42 | +CodeRabbit. |
0 commit comments