Repository navigation
Rewrite parts of documentation #91
Description
The documentation could use some work to make them more user-focused. Right now, they read the way that an LLM would document things for themselves. They were hard for me to read due to the high information density that may be tangential to the topic being documented.
While I think that the issue is very broad, here are some examples:
?nested_tune_grid()talks about "the reproducibility contract" but that is not defined or obvious. Maybe it refers to something in one of the Claude plans?- Almost all of the
@paramentries are excessively verbose and overly detail-oriented. For thenested_tune*_()functions, we should probably inherit the description from the original.resamples,and a few others might need qualifications, but these should be handled in the Details section.- A specific example is for
@param object. This should just be the first sentence. The user does not need to know about the condition class or any other details. - Similarly,
@param param_infoshould be about the object that is required. The current docs cover the entire data analysis process, even down tonested_final_fit().
- A specific example is for
- The use of
--and a lot of AI catch-phrases doesn't give the impression that the documentation was written by a human or for a human. - The examples in the help topics have nested recipe statements. These look like unrolled calls from code that used
|>. - The vignette's overuse of "you" reads like Claude is speaking.
One operational note: the topic files can also benefit from using roxygen2 templates and other tools so that the same text does not need to be duplicated verbatim in different files.
I'd be happy to submit some PRs to refactor various parts of the docs (after our conference is over). Let me know if you agree or would like contributions.
Activity
jmgirard commentedon Sep 10, 2026
I agree, the documentation (readme, vignettes, and roxygen) are all more like placeholders for now. I'll do another automated pass over it tonight to see how that does. If it still reads poorly (which it well may), then maybe you and I can tag-team a human pass?
plan M081, M082: the help pages, guides, README and NEWS rewritten fo…
Rewrite the help pages for a tidymodels user (#92)
Rewrite the guides, README and NEWS for a tidymodels user (#93)
topepo commentedon Sep 11, 2026
Yep. Happy to help.
Guides and README rewritten for a tune_grid user (#94)
topepo commentedon Sep 11, 2026
This skill has worked well for us: https://github.com/AminBlg/SimpleEnglish
jmgirard commentedon Sep 11, 2026
My automated passes are done for vignettes and almost done for the rest. After that lands, I'll sweep over it all one last time with the SimpleEnglish skill you suggested and then plan to start going through and making some manual tweaks. Any help you can provide on the manual improvements after the sweep would be very helpful.
Help pages rewritten for a tune_grid user (#96)
Every help page passes the plain-English sweep (#99)
Help pages inherit tune's argument text and share repeated text throu…
triage: park every candidate row, route one to Known issues, retitle …
jmgirard commentedon Oct 19, 2026
@topepo, I think nestedtune is close to ready for CRAN, and I'd like your help with the last steps.
Since my last update here, I rewrote the help pages, guides, and README to follow tune's and the tidymodels.org articles' length, structure, and voice (#158, #159, #160, #161), and rewrote the DESCRIPTION text for CRAN (#163). That was the automated part. What's left is the human pass we talked about. Could you read through the site and flag anything that still reads like it wasn't written by a person? Comments here, a PR, or a list of pages to rework are all fine. I'll do my own manual pass in parallel.
Once the docs are in shape, are you comfortable with a first CRAN submission? If anything else should change first (API, naming, defaults), I'd rather hear it now than after release.
DESCRIPTION and LICENSE currently name me as the only author and copyright holder. Most tidymodels packages list Posit as copyright holder and funder. I can't remember if we decided this when we last talked. Should nestedtune do the same?
triage: short titles meet the 5-word, 40-character rule