template for new issues --please give me your advice

[wibeasley]

@nutterb, @haozhu233, @rparrish, @sybandrew, @mullen2, @aarenson , and any one else, if you have time, please look at the new issue template that is customized for REDCapR/redcapAPI. I'd appreciate any feedback that could improve the experience for someone encountering a problem.

I'd like something to (a) make it easier for the user to provide useful information with less effort and (b) make it easier for us to help more accurately with fewer back-and-forths. And if the template happens to help the user identify and solve the problem without creating the issue ...then I think everyone is happier too.

I think the issue should leverage the Troubleshooter that 10+ people have contributed to. It should help locate the problematic area more quickly.

@haozhu233, it seems you've liked the template in kableExtra. REDCapR is different in the sense it's more difficult to provide a minimal & self-contained example to reproduce the problem. But with your experience with so many users and issues, I'd love any advice.

@nutterb, I'd like this template to be helpful to redcapAPI too. There are only three quick find-and-replace occurrences of 'REDCapR' -> 'redcapAPI'. And those were mostly to distinguish the R package from REDCap itself.

[aarenson]

• When I tried creating an issue, I was given text that used the format PHI in place of being an actual link. I guess the Markdown isn't being interpreted/rendered? If there's a way to make it an actual link, that would be better, I think.
• I'd probably spell out what PHI stands for, even if it is also linked.

In regards what's asked for, it looks reasonable to me, but I'm far from versed in using REDCapR or dealing with issues related to it.

[wibeasley]

@aarenson, I followed your advice and spelled out 'PHI' the first time it's used. I removed the link just to keep the text simpler. If the user needs a link to PHI, they've got bigger problems when using REDCap.

I appreciate that you haven't used REDCapR much, but @nutterb's and my goal is that at least half of this troubleshooting document helps people who aren't even using R. A lot of these troubleshooting steps involve permissions in the REDCap GUI and Postman. And I'm hoping that a good GitHub issue template could also be plugged in for your phpcap with a few find-and-replaces.

It seems recently, most requests have come from people who aren't REDCap admins themselves. And I'd like our help documents to accommodate them too.

[mullen2]

Will, The template looks good to me. Jim

[haozhu233]

Hi, Will, I think the template looks great! Here are some of my thoughts:

1. I like the troubleshooter section, which reminds me the "similar question" section on stackoverflow. Is it better to shorten this section and move this section before "describe the behavior".

2. I feel like the screenshot section isn't that necessary. People will add screenshot on their own if they think it's needed. Generally, my experience with template is that for those "optional sections", people either delete them all or leave them blank.