For a GitHub repository, the issue tracker is a searchable online forum where the community can ask questions and discuss development. Issue trackers are great because they help make projects self-documenting. For even more convenience, you can maintain an automatically generated FAQ.

  1. Label your favorite issues as frequently asked questions.
  2. Scrape these labeled issues from the tracker using GitHub’s REST API.
  3. Use code to compile an index of links to the original issues.

Example

In the GitHub repo of the drake R package, I flag pedagogically useful issues with the “frequently asked question” label. I periodically run docs.R to generate an FAQ vignette and turn it into an online FAQ.

Code

I use the gh package to interact with GitHub.

library(gh)
library(tidyverse)

I define a couple supporting functions below. The tidyverse has more elegant solutions, but I am behind the curve.

is_faq <- function(label){
  identical(label$name, "frequently asked question")
}

any_faq_label <- function(issue){
  any(vapply(issue$labels, is_faq, logical(1)))
}

Next, I scrape the issue tracker to get a list of FAQ issues.

faq <- gh(
  "GET /repos/ropensci/drake/issues?state=all",
  .limit = Inf
) %>%
  Filter(f = any_faq_label)

I quickly hit my limit of gh() queries, so I use this guide explains how to obtain a personal access token. Adding Sys.setenv(GITHUB_TOKEN ="YOURAPITOKENWITHFUNKYNUMBERSHERE") to my .Rprofile file seems to solve the problem. The gh() function also has a .token argument. ("YOURAPITOKENWITHFUNKYNUMBERSHERE" is not my actual token.)

Next, I create a text vector of links to the actual issues.

combine_fields <- function(lst, field){
  map_chr(lst, function(x){
    x[[field]]
  })
}
titles <- combine_fields(faq, "title")
urls <- combine_fields(faq, "html_url")
links <- paste0("- [", titles, "](", urls, ")")

Finally, I move this FAQ stub to the vignettes folder and append the links.

starter <- system.file(
  file.path("stubs", "faq.Rmd"),
  package = "drake",
  mustWork = TRUE
)
dir <- rprojroot::find_root(criterion = "DESCRIPTION", path = getwd())
dest <- file.path(dir, "vignettes", "faq.Rmd")
tmp <- file.copy(
  from = starter,
  to = dest,
  overwrite = TRUE
)
con <- file(dest, "a")
writeLines(c("", links), con)
close(con)

Because the FAQ is an R package vignette, pkgdown automatically turns it into a webpage “article”. Some extra lines in drake’s _pkgdown.yml file add “FAQ” to the navbar of the documentation website.

This technique adds convenience and automation, but it is tough to set up from the beginning. I nudged GitHub to consider native support for automated FAQs.

Thanks

Thanks to Jenny Bryan, Mäelle Salmon, Noam Ross, and Jeff Kriske for pointing me to great tools for interacting with the GitHub API.