docs: voice audit — rewrite AI-written documentation in John's voice#92
Open
ehrlinger wants to merge 19 commits into
Open
docs: voice audit — rewrite AI-written documentation in John's voice#92ehrlinger wants to merge 19 commits into
ehrlinger wants to merge 19 commits into
Conversation
Plan to audit all ggRandomForests docs (roxygen, vignettes, README, NEWS) and rewrite AI-written portions in John's voice. Approach: build a two- register voice fingerprint from JSS-era prose + supplied writing samples, classify every doc surface, rewrite only the AI/mixed surfaces. Voice-only: no factual/content changes. Ships as one PR before the v2.8.0 RC.
Per review: add 'don't overstate' rule, log ellipses as informal-register habit, and distinguish mechanical parallelism (an AI tell) from pedagogical repetition (kept — it is the voice).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
print_helpers.R, ribbon_style.R, utils.R carry zero roxygen lines and produce no man pages; they are out of scope for a documentation voice audit. Earlier pass over-classified them as AI/rewrite.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #92 +/- ##
=======================================
Coverage 87.31% 87.31%
=======================================
Files 38 38
Lines 3098 3098
=======================================
Hits 2705 2705
Misses 393 393
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR standardizes the documentation voice across ggRandomForests so that newer AI-era prose reads in a consistent “John” narrative/terse register, while keeping code, signatures, examples, and references unchanged.
Changes:
- Rewrites vignette / README / NEWS prose to a consistent narrative + terse voice.
- Rewrites roxygen blocks for newer/mixed surfaces (varPro family, ROC/variable/partial/brier, print/summary/autoplot), regenerating matching
.Rdpages. - Adds documentation-process artifacts under
dev/(voice fingerprint, classification table, design + implementation plan).
Reviewed changes
Copilot reviewed 41 out of 46 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| vignettes/ggRandomForests.qmd | Rewrite intro/explanatory prose and “Next steps” bullets in vignette voice. |
| vignettes/ggRandomForests-survival.qmd | Rewrite Brier/CRPS section prose and conclusion summary voice. |
| vignettes/ggRandomForests-regression.qmd | Rewrite select explanatory + conclusion prose voice. |
| README.md | Rewrite S3-method and “Why ggRandomForests?” prose for consistent voice. |
| NEWS.md | Rewrite v2.8.0 development bullets into the terse register. |
| R/varpro_feature_names.R | Roxygen wording rewrite (voice-only). |
| R/surv_partial.rfsrc.R | Roxygen wording rewrite (voice-only). |
| R/summary_methods.R | Roxygen wording rewrite (voice-only). |
| R/print_methods.R | Roxygen wording rewrite (voice-only). |
| R/autoplot_methods.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_varpro.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_variable.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_udependent.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_roc.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_partial_varpro.R | Roxygen wording rewrite (voice-only). |
| R/plot.gg_brier.R | Roxygen wording rewrite (voice-only). |
| R/gg_varpro.R | Roxygen wording rewrite (voice-only). |
| R/gg_variable.R | Roxygen wording rewrite (voice-only). |
| R/gg_udependent.R | Roxygen wording rewrite (voice-only). |
| R/gg_roc.R | Roxygen wording rewrite (voice-only). |
| R/gg_partialpro.R | Deprecation roxygen wording rewrite (voice-only). |
| R/gg_partial_varpro.R | Roxygen wording rewrite (voice-only). |
| R/gg_partial_rfsrc.R | Roxygen wording rewrite (voice-only). |
| R/gg_brier.R | Roxygen wording rewrite (voice-only). |
| man/varpro_feature_names.Rd | Regenerated Rd to match roxygen voice edits. |
| man/surv_partial.rfsrc.Rd | Regenerated Rd to match roxygen voice edits. |
| man/summary.gg.Rd | Regenerated Rd to match roxygen voice edits. |
| man/print.gg.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_varpro.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_variable.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_udependent.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_roc.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_partial_varpro.Rd | Regenerated Rd to match roxygen voice edits. |
| man/plot.gg_brier.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_varpro.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_variable.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_udependent.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_roc.rfsrc.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_partial_varpro.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_partial_rfsrc.Rd | Regenerated Rd to match roxygen voice edits. |
| man/gg_brier.Rd | Regenerated Rd to match roxygen voice edits. |
| man/autoplot.gg.Rd | Regenerated Rd to match roxygen voice edits. |
| dev/voice-fingerprint.md | Adds the two-register voice reference used as the rewrite yardstick. |
| dev/voice-audit-classification.md | Adds an auditable classification table for rewrite scope. |
| dev/plans/2026-05-22-doc-voice-audit-plan.md | Adds the implementation plan for the audit/rewrite work. |
| dev/plans/2026-05-22-doc-voice-audit-design.md | Adds the design spec and guardrails for voice-only changes. |
Files not reviewed (5)
- man/autoplot.gg.Rd: Language not supported
- man/gg_brier.Rd: Language not supported
- man/gg_partial_rfsrc.Rd: Language not supported
- man/gg_partial_varpro.Rd: Language not supported
- man/gg_roc.rfsrc.Rd: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+117
to
+118
| * Every `gg_*` object is a plain data frame underneath, so you can skip the | ||
| `plot()` methods entirely and build the figure yourself with `ggplot2`. |
| `ggplot2` figure. Two things follow from that split. | ||
|
|
||
| First, the data object stands on its own. It carries everything its plot needs, so you can save it, | ||
| inspect it, or come back to it later without keeping the original forest --- which can be large --- |
Comment on lines
+17
to
+20
| #' a curve against time. A lower curve means a better-calibrated forecast. | ||
| #' Turn \code{envelope = TRUE} on and the overall line picks up a ribbon | ||
| #' spanning the 15th to 85th percentile of the per-subject contributions, | ||
| #' which shows how much the score varies across subjects at each time. |
Comment on lines
+652
to
+654
| Notice the pattern. Each `gg_*()` function returns a plain tidy data frame; | ||
| the plotting comes after. Lean on the package's `plot()` methods when the | ||
| default figure works, and drop down to `ggplot2` directly when it does not. |
Comment on lines
+411
to
+414
| Notice the pattern in all of this. Each `gg_*()` function returns a plain | ||
| tidy data frame; the plotting is a separate step. Use the package's `plot()` | ||
| methods when the default figure is what you want, and reach for `ggplot2` | ||
| directly when it is not. |
Comment on lines
+83
to
+86
| Each `gg_*` function has a matching `plot()` S3 method that hands back a `ggplot2` object, so you can keep | ||
| adding layers, scales, or a theme. Every `gg_*` object also has `print()` and `summary()` methods: `print()` | ||
| shows a short header at the REPL rather than dumping every row (use `head()` when you want the rows), and | ||
| `summary()` gives you a diagnostics object you can print or keep. |
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
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.
Summary
Rewrites the AI-written documentation across ggRandomForests so the package reads in one consistent human voice. Voice-only: no factual or content changes. Function signatures, argument names, return-value facts, example code, version numbers, and issue references are unchanged.
Covers roxygen (varPro family, gg_brier, ROC/randomForest surface, gg_partial family, S3 methods), the three vignettes, README, and the v2.8.0 NEWS entries. Mixed files had only their 2026-era AI prose rewritten; original JSS-era prose was left untouched.
Adds
dev/voice-fingerprint.md(the two-register voice reference, synced from the author's vault) anddev/voice-audit-classification.md(records what was and was not in scope). Design spec and implementation plan are indev/plans/.Test plan