Blog post based on Collaborative Coding slides

[cwickham]

Slides from useR! 2017

While I think the slides did an OK job motivating people to contribute and maybe what types of contributions might be good to start with, it didn't really give enough detail for someone to get started.

I think contributing to documentation is a great place to start, but if you are new to github and R packages, you might be wondering:

• Where do I find the file to edit?
• What is roxygen2 and why might it matter to a typo fix?
• Is there any etiquette I need to know?

An idea I had done a little brainstorming on was a series of blog posts that walk though making pull requests on github that contribute to documentation in R packages, or related R resources (e.g. bookdown source). Starting with the simplest case, edits that can be made entirely on the github website, and getting to a slightly more complicated case where you'd need to fork, clone in RStudio, edit, document(), check(), push, PR.

Here's some notes I found on the matter that I'd written some time last year:

Fixing typos in R package documentation

Things you can contribute to:

• Help files displayed in R
• README on github
• Package vignettes
• Package websites with source hosted on github

Why fix typos?

• The maintainer will prefer a typo fix to a typo report.
• It's low stakes. You are unlikely to break anything by fixing documentation, but it gives you practice contributing.
• You can improve the experience for the next person who uses the documentation.

Easiest case

The typo can be fixed directly in the file on github. This is super easy becasue you can do everything right on github.

Steps:

1. Find the right file to make the change
2. Make the edit directly
3. Submit the pull request

Appropriate when the content you are fixing is in a single file, and that file is not used to generate any other files in the repository. It's easier to talk about exceptions, you can't use this method for:

• R help documentation generated using roxygen2
• README.md when it is being generated by README.Rmd
• website files (i.e. HTML) that are generated from RMarkdown

One step up

The typo needs the documentation to be regenerated.

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plugin-providers.R

[hturner]

One post might also focus on how developers can make their repo more beginner friendly. This might include labeling issues good-first-issue (c.f. #20), adding a CONTRIBUTING.md, adding a first PR welcom badge as suggested here: https://twitter.com/crazy4pi314/status/1005191234535620609?s=19 (h/t @maelle).

[hturner]

May we could tie in with hacktoberfest?

[maelle]

I edited a typo in your comment @cwickham 😉 ("vingettes")

I love this idea of a series! 🎊

I wonder whether a screencast would have some value here?

[cwickham]

PRs from R are now a little easier with usethis:
https://usethis.r-lib.org/articles/articles/pr-functions.html

[cwickham]

This was the blog post (?) I remember hearing about: https://github.com/thisisnic/first-contributions

It's both a walk through of the PR process (with RStudio focus) and safe place to make a PR to add your name to contributors.md.