FAQ Document?

[tiernanmartin]

I see that you've created the Frequently Asked Question tag for issues - is there an FAQ document with the answers to these questions?

Just in case the value of such a doc isn't clear, I just spent a good while trying to figure out how to set triggers for one of my plans. You've done an excellent job documenting this functionality in the debugging vignette, but it took me a while to figure out where I should be looking for this information because I didn't yet know that "triggers" is the keyword I was searching for. An FAQ could help reduce the about of time users spend scanning the documentation looking for a specific piece of info.

Just food for thought!

[wlandau]

Thanks, @tiernanmartin. It's definitely on my radar, but I don't plan to write it just yet. (I'm almost completely focused on #227 and especially #232 right now.) And I hesitate to write it as a vignette because I want casual drive-by contributions to be easy. I think a GitHub repo wiki would be more appropriate. Does that sound good?

[tiernanmartin]

A GitHub repo wiki is exactly what I had in mind 👍

[wlandau]

Just added a wiki at https://github.com/ropensci/drake/wiki/Frequently-Asked-Questions. It will be a while before I have the chance to add anything myself, but for the long term, I expect content to be user-driven.

[tiernanmartin]

Great!

[wlandau]

Reopening because I think the issues tagged "Frequently Asked Question" can be used to start the wiki.

[wlandau]

I also hope the FAQ will be community-maintained, so I am adding a "help wanted" tag.

[tiernanmartin]

This is my first time contributing to a repo wiki, so apologies in advance if I'm going about it the wrong way.

I cloned the drake repo but couldn't find the wiki.md file, so I followed the steps suggested here and created a separate wiki repo: https://github.com/tiernanmartin/drake-wiki/. I only added two questions but hopefully that's good enough to get it up and running.

I've since realized that actually you (the owner of the original repo) need to create a separate wiki repo for me to send pull requests to. Then you set the wiki repo to sync with the drake repo wiki, as explained here in the guide.

... that's all a bit more complicated than I expected it would be (yay FOSS!) - let me know what you'd like me to do next.

Thanks!

[wlandau]

@tiernanmartin Thanks so much for helping out! I could create github.com/wlandau/drake-wiki, but I'm not sure it would help because drake is now an rOpenSci package. @maelle, could we create github.com/ropensci/drake-wiki? Can I create it myself and transfer ownership, or should it go through an editor?

[maelle]

I'll inform myself.

What's the difference between the wiki and having say a FAQ in the pkgdown website? The easier contributions as you say? Just curious!

And why having a separate repo for the wiki?

[tiernanmartin]

@maelle It's a good question and not one I have the answer to. It may be easier to just make an FAQ page on the pkgdown site. As I said in the post above, this is my first time trying to contribute to an GitHub repo wiki and I didn't realize it would be a somewhat involved task.

I think the most straight-forward way to allow users to contribute to the wiki would be to deselect the 'Restrict editing to collaborators only' option on the ropensci/drake repo:

The blog post I shared above (Enabling pull requests on GitHub wikis) details a more complicated way to set up a wiki that can accept pull requests. Unfortunately, it requires that the repo owner create a separate wiki repo and set up a syncing connection with Travis CI.

From the blog:

The technique works by cloning the wiki, pushing it to a new repository so that pull requests can be put out against it, then creating a CI build that automates syncing between the two repositories.

While it takes a bit of work to setup, it’s a really nice experience for collaborators and users afterwards.

The author goes on to detail the steps of setting up the syncing connection...

Honestly, I'm not sure it's worth the hassle.

[wlandau]

Yeah, the purpose of the wiki FAQ is to make it easy for everyone to contribute, regardless of familiarity with pull requests or even a GitHub account. GitHub may not actually be the right place for it, I don't know.

[maelle]

You can create and transfer it if you wish, but good that you asked! cc @sckott

And thanks both for your answers!

I must say I've never read a GitHub wiki but I can see the advantages you mention.

[wlandau]

Thanks to @noamross and @jennybc for their advice on the rOpenSci Slack. Rather than use a GitHub wiki, I think we can start the FAQ as a vignette / pkgdown article and invite contributions with this approach. We plenty of FAQ issues to start with. We can compile them in one place and explain the final answers concisely.

[tiernanmartin]

That sounds good.

Feel free to use the Frequently-Asked-Questions.Rmd I started or throw it out and start from scratch.

[wlandau]

More thoughts: I'm already tagging GitHub issues as FAQs, and I don't think we should duplicate the effort in a large vignette. How about this:

1. For each issue tagged as a "Frequently Asked Question", include a comment somewhere in the thread that completely describes the end solution.
2. Create an index of links to those comments in either a top-level FAQ.md or a vignette.

[wlandau]

Maybe we could even auto-generate the index. @jekriske, didn't you mention a way to programatically interact with GitHub issue trackers?

[jekriske]

Yes, through the github api
https://developer.github.com/v3/issues/
There are a couple of R packages that interact with the api as well. You'll just need an access token.

[wlandau]

Thanks, Jeff. Just heard about @coatless's ghapi package](https://github.com/coatless/ghapi).

[wlandau]

Just added an FAQ vignette and online article. I used gh to scrape issues labeled "frequently asked question" and compile an index. I will refresh the index periodically.

I am confident that this will help let the docs flow and avoid duplicated effort. Thanks @maelle, @jennybc, @cboettig, and @noamross for steering me in the right direction.

[wlandau]

Some shared learnings: https://wlandau.github.io/2018/02/24/github-faq/

[wlandau]

Maybe probot could improve the current solution (and the rest of docs.R). I don't know.