Rewrite parts of documentation
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 48/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- r
- Domain
- documentation
Research direction
Start by locating the topic files for nested_tune_grid() and the other nested_tune*_() functions, then review the related vignette and repeated @param entries. Compare the current wording with the requested user-focused examples and identify where roxygen2 templates could remove duplication. Done means the selected documentation is clearer, less verbose, and avoids unnecessary implementation detail.
Written by the indexing model from the issue text.
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.
- Dominant language
- R
- Stars
- 1
- Forks
- 1
- Avg merge
- 2h 24m
- Merged PRs (30d)
- 60
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Huber-group-EMBL/Rarr#257 ·
Maintainers usually reply within 1 day