Closed MilesMcBain closed 3 years ago
This is a good point. For a project like this, a stack overflow tag seems like overfill. Do we think referring the user to vignettes and pkgdown site first for help, then telling them to open an issue for help would be sufficient?
A thing I've seen done is using the GitHub issue templates to create checklist of things you expect the user to have done before seeking support. You can have separate templates for bugs vs feature requests vs support if you want.
Here's the template from https://github.com/rstudio/rmarkdown/issues/new
<!--
Please keep the below portion in your issue. Your issue will be closed if any of the boxes is not checked (i.e., replace `[ ]` by `[x]`). In certain (rare) cases, you may be exempted if you give a brief explanation (e.g., you are only making a suggestion for improvement). Thanks!
-->
---
By filing an issue to this repo, I promise that
- [ ] I have fully read the issue guide at https://yihui.org/issue/.
- [ ] I have provided the necessary information about my issue.
- If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
- If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included `xfun::session_info('rmarkdown')`. I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: `remotes::install_github('rstudio/rmarkdown')`.
- If I have posted the same issue elsewhere, I have also mentioned it in this issue.
- [ ] I have learned the Github Markdown syntax, and formatted my issue correctly.
I understand that my issue may be closed if I don't fulfill my promises.
You could also use this to set expectations as to the level of support provided. E.g. you could say support is best effort, but responses to support requests may take some time etc. quicker responses may be had by asking on Stack Overflow, or the #rstats hashtag on Twitter, or any other relevant communities.
Oh I do like the checklist ✅ proposal. Tx @MilesMcBain.
My sense is that the language on the rmarkdown issue template is stronger than the what we want. Yihue gets so many more requests will a huge user base so I can understand maintaining judiciously structured issues. In our case, we still have a relatively small user base including many R beginners. We want people to open issues even if they aren't perfectly formatted or have a complete reprex. We don't want to scare folks off. With that in mind I am thinking about this issue template which is taken almost verbatim from usethis:
---
name: Bug report or feature request
about: Describe a bug you've seen or make a case for a new feature
---
Please briefly describe your problem and what output you expect. Please include a link to the catalogue record that you are trying to access if applicable.
Please include a minimal reproducible example (AKA a reprex). If you've never heard of a [reprex](http://reprex.tidyverse.org/) before, start by reading <https://www.tidyverse.org/help/#reprex>.
Brief description of the problem
```r
# insert reprex here
An element of the Community Guidelines documentation checklist item is that you should provide clear guidelines for third parties who want to seek support.
In your README I see:
Which is not quite clear direction as to what someone should do if they're in the "Getting Help" category.
edit: link review thread: https://github.com/openjournals/joss-reviews/issues/2927