Add a feedback form to reference pages

[nickmcintyre]

Increasing Access

The website currently directs visitors to GitHub if they'd like to provide feedback. This approach isn't accessible for people without GitHub accounts, especially K–12 students.

Most appropriate sub-area of p5.js?

Reference

Feature request details

@limzykenneth @davepagurek @Qianqianye I think it would be helpful to link to a minimal feedback form at the bottom of reference pages. The form could be owned by a @p5js.org Google account and responses could be shared with documentation contributors. What do y'all think?

[Qianqianye]

Thanks @nickmcintyre for the suggestion.
I agree that using Google form would be easier for a lot of users, like K12 students. However, we have been having hard time maintaining and checking response updates of Google forms historically. During the transition of old and new contributors, we often find the responses left neglected and information scattered on GitHub and Google forms.

It'd be great if we could come up with a systems that gather information at a centralized location, like GitHub. How about a solution like this one: Create a new GitHub Issue from a Google Form submission?

[davepagurek]

That's a good suggestion @Qianqianye! We could set that up and see how it works. Hopefully it gives us more high quality feedback; if we start getting a lot of bot spam we can always update the form to e.g. require an email or something.

[nickmcintyre]

Thanks @Qianqianye and @davepagurek! Good suggestion to integrate the Google form into our existing workflow. I'll tinker with an example and will let you know how it goes.

[nickmcintyre]

This approach works well! I used a test repository and an access token that was limited to read/write issues in that repository. Here's an updated version of the script that executes on form submissions:

const ghToken = "github_pat_abc123";

function onFormSubmit(e) {

  const title = `Reference feedback: ${e.values[1]}`;

  const body = `
  <h2>Reference Page</h2>

  <p>${e.values[1]}</p>

  <h2>Problem Description</h2>

  <p>${e.values[2]}</p>

  <h2>Focus Area</h2>

  <p>${e.values[3]}</p>

  <h2>Suggested Fix</h2>

  <p>${e.values[4]}</p>
  `;

  const payload = {
    "title": title,
    "body": body
  };

  const options = {
    "method": "POST",
    "headers": {
      "authorization": `token ${ghToken}`,
      "Accept": "application/vnd.github.v3+json",
    },
    "contentType": "application/json",
    "payload": JSON.stringify(payload)
  };

  const response = UrlFetchApp.fetch("https://github.com/api/repos/processing/p5.js/issues", options);
}

I opted to leave information about learning environment in the spreadsheet for later review.

Happy to revise the form and issue template. Once we have workable versions, how/where should we integrate the form into the website?

[limzykenneth]

One thing about using a Google Form to open a GitHub issue is that it could possibly make follow up difficult, with Github Issues mostly be filling in a form already, going through Google Form to do the same thing feels a bit redundant, although I get the point about having a GitHub account may not be feasible for some as well.

I think one of the major value, especially for education, in opening a GitHub issue and contributing on GitHub is the possibility of community engagement and feedback. Having just a place that seemingly send queries into the ether isn't ideal in my opinion, it also makes further follow up questions we may have difficult to get answer to (eg. asking to clarify problems faced in the issue).

Are other avenues such as the Processing forum or Discord be possible places to direct people to instead of GitHub? It can also possibly be prefilled new posts relating to the specific reference entry when clicked on the relevant link so most of the info is prefilled?

[nickmcintyre]

@limzykenneth issues submitted using this approach are anonymous by design, so follow up would be impossible. It would be up to contributors to act on feedback. The general idea is that a twelve year-old can easily point out documentation that isn't clear to them. They won't necessarily know how to revise it, but they can tell us where to focus.

In the US, K–12 students will have a hard/impossible time joining GitHub as part of class due to helpful legal safeguards. The same goes for Discourse and Discord. Anecdotally, my old school district's IT department wouldn't have approved using any of these services for class.

I'm working with a community member in the NYC Department of Education to help direct students to the p5.js website in an organic way. That's taken the form of a set of coding challenges that require a bit of research and a friendly request to contribute feedback. Gotta bootstrap the process somehow. It's very much an experiment, but a simple form seems likely to cause the least amount of friction for everyone.