Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Make help pages and examples clear and practical

Open
  • Is something wrong?
#26 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
Half a day
Newbie friendliness
55/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
r
Domain
documentation

Research direction

Start with the scoped entry point the issue names: the roxygen block above compare_nested_models() in R/ and its generated man/compare_nested_models.Rd. Read the function's existing help and code to see what the output columns mean, reorder the help so 'when to use' and 'how to read the output' come before compatibility checks, and keep the example. Regenerate with devtools::document() and verify rendered help; note the issue flags statistical caveats (nesting, variance at boundary) that must stay visible.

Written by the indexing model from the issue text.

Description

documentation priority: medium

Goal

Make function help and examples easier to use: explain the purpose, show an example, explain results and common choices, then give technical details. Start from #18's diagnostic documentation. #25 covers README and vignette structure; #23 covers making documentation easier to find.

Tasks

  • Contributor guidance: briefly explain in .github/CONTRIBUTING.md: use plain language, spell out acronyms on first use, show useful output, and link to one main explanation instead of repeating it. Keep short pages short; do not turn internal documentation into tutorials.
  • prepare_dyad_data() help: show a minimal workflow and explain generated columns before naming rules and stored information.
  • recover_exchangeable_covariance() help: start with the default call and explain partners' standard deviations and correlations. Cover automatic block matching, custom pairings, and omitted blocks later.
  • compare_nested_models() help: explain when to use it and how to read the output before describing compatibility checks.
  • Package help: keep it brief. Spell out APIM, DIM, and DSM on first use; update starting links to match #25.
  • Columns missing from the fitted model frame: show dyad and role as column names in the predictive-check vignette. When either column is absent from the fitted model frame, pass the unchanged fitting data with data = example_data; omitted rows are handled automatically. Link to check_partner_dependence() argument details. Use column names, not external vectors, for prepare_dyad_data() identifiers too.
  • Examples that need glmmTMB, after #18: replace visible if (requireNamespace("glmmTMB", quietly = TRUE)) { ... } wrappers with @examplesIf requireNamespace("glmmTMB", quietly = TRUE) in check_partner_dependence(), compare_nested_models(), and recover_exchangeable_covariance(). Show plain, unindented code; run it only when optional package glmmTMB is installed. Regenerate help, inspect help and pkgdown examples, and check execution with and without glmmTMB. See roxygen2 guidance.
  • Bundled simulated datasets: use these instead of inline data.frame() construction or ad hoc simulation in function help, README examples, and vignettes. Choose the appropriate cross-sectional or longitudinal dataset. Subset when helpful, e.g., example_data <- dyads_cross[dyads_cross$coupleID <= 40, ]. Select whole dyads by ID, not row position. Choose IDs for the intended composition: coupleID <= 40 contains only female-male dyads. Keep required measurement occasions in longitudinal examples. Check model convergence and intended results.

Done when

Preserve statistical meaning and function behavior. Keep missing-data and member-role assumptions visible. Explain latent versus response-scale covariance and model-comparison limits involving nesting or variance parameters at a boundary. Edit roxygen and vignette sources, regenerate outputs, run examples, and check rendered help and links.

Use small pull requests. Start with only compare_nested_models() help and its generated Rd file, retaining the example. This issue is too broad for good first issue. Internal maintenance remains in #33.

Dominant language
R
Stars
1
Forks
2
Avg merge
9h 28m
Merged PRs (30d)
21

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Pascal-Kueng/dyadMLM

All issues in Pascal-Kueng/dyadMLM

Similar issues

More R issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.