Ideally, I Hope to Simply Copy and Run Your Example

When you ask questions or file bug reports, you want to get answers and solutions as quickly as possible, right? If that is the case, I’d like to talk about a very common situation in questions and bug reports in this post. Basically, if I’m unable to answer the question due to lack of information or reproducible examples the first time I see it, I’m likely to skip it and won’t come back for the second time, unless I happen to be free and happy enough to remind a user for the 502nd time about reproducible examples, or ask 12 questions for complete information. I believe most users understand this, but every now and then, I receive “reproducible examples” in the form of verbal descriptions when a full example can speak for itself. Had a full example been provided, I could be able to simply copy and run it, and hopefully see the problem immediately, instead of following a number of steps from the verbal description to prepare the example by myself.

Words can be ambiguous. Code is precise.

That is why you should provide a fully reproducible example whenever possible, instead of describing all the steps to create such an example.

I have seen this kind of issues many times in the past, and finally decided to write this post after I saw yihui/knitr#1562 yesterday.¹ Think about the work I had to do for this issue:

• For step 1, I had to copy it to an Rmd document in my RStudio session.

• For step 2, I had to copy the code and put it in an R code chunk.

• For step 3, I had to add more headers, and it was unclear how many “more headers” or what kind of headers I would need. I added two, but didn’t realize the problem for some reason.

• For step 4, I tried, but since step 3 was unclear to me, I didn’t know what I should be looking at.

In terms of the structure, this is actually a pretty good bug report. It stated the steps to reproduce the problem, and the expected behavior. But I can’t simply copy and run an example. I just can’t.

I asked for a full reproducible example, and finally realized that I should be looking at the two elements “title” and “title2” in the TOC. Within five seconds, I was able to reproducible the problem after I copied and ran the full example.

BTW, when you discover bugs about something that you can see on your screen, screenshots can be highly useful. They can be strong evidence of bugs. Although it is not really what I think in my head, but when you file a bug report, you may imagine that the developer would deny it if you don’t show enough evidence. If you provide a relatively simple reproducible example and attach screenshots, there will be no way for me to escape but acknowledge the problem, which means a much higher chance to fix it.

Donate

As a freelancer (currently working as a contractor) and a dad of three kids, I truly appreciate your donation to support my writing and open-source software development! Your contribution helps me cope with financial uncertainty better, so I can spend more time on producing high-quality content and software. You can make a donation through methods below.

• Venmo: @yihui_xie, or Zelle: xie@yihui.name

• Paypal

  • If you have a Paypal account, you can follow the link https://paypal.me/YihuiXie or find me on Paypal via my email xie@yihui.name. Please choose the payment type as “Family and Friends” (instead of “Goods and Services”) to avoid extra fees.

  • If you don’t have Paypal, you may donate through this link via your debit or credit card. Paypal will charge a fee on my side.

• Other ways:

  WeChat Pay (微信支付：谢益辉)	Alipay (支付宝：谢益辉)

When sending money, please be sure to add a note “gift” or “donation” if possible, so it won’t be treated as my taxable income but a genuine gift. Needless to say, donation is completely voluntary and I appreciate any amount you can give.

Please feel free to email me if you prefer a different way to give. Thank you very much!

I’ll give back a significant portion of the donations to the open-source community and charities. For the record, I received about $30,000 in total (before tax) in 2024-25, and gave back about $15,000 (after tax).