Thoughts about talking about reprexes

[wlandau]

I would like to share some thoughts on reprexes. I do not have any specific requests for code or documentation changes in the reprex package itself, but I would like to post this thread in case the maintainers find it useful.

I regularly find myself in a situation common to package maintainers: a user loosely describes an error and asks what might be the cause. Naturally, the error seems as strange to me as it does to the user, and I ask for a reprex. Sometimes the reprex is incomplete and not runnable, and other times the user does not provide one and instead requests that I speculate on a “likely” solution. As the discussion progresses, eventually they understand that as a package maintainer I do not have perfect knowledge. However, it is a lot of work to get there for each individual user. I find it hard to take a step back and explain the purpose of a reprex from first principles, and I find that I have to do this a lot.

I think the disconnect comes from an implicit difference of epistemology: the user insists on appealing to the expertise and authority of the maintainer, and the maintainer insists on extreme empiricism. So for targets, I wrote a new chapter in the user manual on how to ask for help, and I hope it bridges this and other gaps. From https://books.ropensci.org/targets/help.html#post-the-complete-context:

Computer code is extremely strict. In order to run properly, it needs to be exactly correct, down to the last detail. That makes every single piece of every single computer program susceptible to programming errors and usage errors. For every bug you discover, there are hundreds of strange and unguessable potential causes. The culprit could be a typo buried deep in the targets codebase, an incorrect hidden assumption lost in translation about how to use targets, an obscure bug in an obscure R package dependency, a mistake in one of your R functions, or some other mysterious or unexpected reason. In addition, you may be the first user to experience the problem. So when you ask for help, it is not enough to state the error and ask what might be the solution. The true answer is too surprising to predict, even for the most experienced experts of R and targets.

To receive useful feedback, please provide the complete context of the problem, including a reprex. The purpose of a reprex, or reproducible example1, is to eliminate the knowledge gaps, misunderstandings, and hidden assumptions where bugs hide. A reprex is a sample of complete, self-contained, runnable code that fully emulates and reproduces the problem. The code should look clean and readable, be as short and concise as possible, run in as few seconds as possible, and contain only the details most relevant to troubleshooting. You can embed the code inline in your question, or you can upload it to a public repository and post the link. Regardless, please expect that anyone trying to help will read all the code and run the enclosed _targets.R file on their own private computer. Please make this utterly empirical process as quick and easy as possible for the people who volunteer their valuable time and energy to answer questions.

[hadley]

Thanks for sharing. Definitely agree that this is a common problem and I does seem like it's out of scope for the reprex package. I do think you're doing the right thing by providing more context for the users of your package, and that is something we've done in a few places (e.g. https://dbplyr.tidyverse.org/articles/reprex.html).