Link to file an issue about the page you're viewing

[peterbe]

Fixes #1342

This is what it looks like in the footer:

This is the first thing you see when you click on it (in the new tab):

When previewing:

[peterbe]

I kinda wish the title was better. As it stands now, the user isn't encouraged to enter anything additional that sets this apart.
We might one day have tens or hundreds of issues that all just start with "Problem with content - $URL" when it would be good if the title could have useful expressions like "Code example isn't working" or "Typo in the introduction".

Another thing is perhaps to include, after the MDN URL : $URL something like a checklist that looks something like this:

<!-- Select one or more that apply. This helps us help you. -->

- [ ] General issue
- [ ] Speling misstake(s)
- [ ] Code example (if checked, please specify more)
- [ ] Lacking information
- [ ] Detail factually incorrect or unclear
- [ ] Other (please type more about it below)

But the truth is GitHub issue checklists aren't great for typing because you have to manually put in a little x. However, they do set a certain tone that triggers the reporter to express themselves more. What do you think?

[fiji-flo]

One option would be to fill out some things while still being on MDN and add this information via the query string?

[peterbe]

One option would be to fill out some things while still being on MDN and add this information via the query string?

Yes! After all, we can leverage the fact that it's client-side only and so we can code split a fancy UI thing that suddenly appears. Like a form that looks something like this:

<form action="https://github.com/mdn/content/issues/new" method="get">
<input type=hidden name=title value={title}/>
<input type=hidden name=body value={body}/>
<button type=submit>Save on GitHub</button>
</form>

So, no auth needed.

Does that make sense @chrisdavidmills ? Is that something you'd support? Perhaps we land this PR as is and then tackle those clever ideas (thanks @fiji-flo !) in a followup.

[peterbe]

Another interesting option to consider is using ... like they do here.
E.g. our suggested title could be:

On /en-US/docs/MDN/Kitchensink ...

to inspire the person to replace and fill out the ...

[peterbe]

Also, @chrisdavidmills is there a GItHub issue label that you think we should default to? E.g. needs triage

[chrisdavidmills]

Hi @peterbe!

I think this looks mostly fine, certainly good enough to put into the Yari beta test, at which point we can get some feedback from the testers on how they feel about it, and what would make them more likely to give us the most useful information off the bat.

One thing I would like to have on the MDN page would be a heading above the two links, to draw people's attention to the links and make it a clearer call to section. The heading coud be something like "Found a problem with this page?", and then the two links could be "Edit the source on GitHub" and "File a GitHub issue to report the problem".

A follow up question would be — when you click the "Edit the source..." link, where exactly would that take you? Directly to the GitHub page for that content, so you can press the edit button and make a change that way, or directly to a contribution guide page that tells you how to edit MDN most effectively? I would say that the former would be the best context aware option that would have a higher success rate, but there should also be a link to the latter easily available from that page. If possible, each source code page should have that link easily available.

For the heading, I think this is a hard problem. MDN URL : $URL is fairly useful, and it is great that you are also including a clickable link to the problem page in the body of the issue (currently you have to copy the URL out of the title and paste it into a new tab, which is really annoying). One suggestion might be to set the issue title as Issue with "$PAGE_TITLE": ... with dots to encourage more detail being added, but also limit the $PAGE_TITLE to a certain number of characters (say 20 or 30) to keep it manageable?

You can try the checklist thing, but I think it will be rarely helpful. It isn't at the moment. One thing I did like was John Whitlock's suggestion of adding the default option at the bottom as "Please close this issue, I accidentally submitted it without providing any details" ;-)

I like the idea of experimenting with filling out the information on the MDN side rather than the GitHub side. Perhaps you could include a select menu containing the options for the types of problem to report in there?

Would it be worth running an A/B test to see which method of collecting feedback elicits more reports, and more useful reports?

Lastly, I think the needs triage label is useful; I'd also love to automatically generate a label pertaining to the type of content it relates to, so for example if it is under /Web/API, you get a label of "Content:WebAPI", if it is under CSS you get a label of "Content:CSS", etc.

The content areas we need to have different labes for (imo) are HTML, CSS, JavaScript, WebAPI, WebExt, DevTools, A11y, HTTP, Learn, and Other for anything else.

And as a follow on from that, I would love to know if we can use those labels to automatically place those issues in GitHub projects? At the moment we have different projects for the different content areas: https://github.com/mdn/sprints/projects

OK, that's it for now; this is rapidly becoming an essay ;-)

[peterbe]

Quick note (I'm on PTO but on my phone)...
I'll act on those things next week. With regards to the phrase and meaning of "Edit on GitHub" I think the simple solution is to go back to basics and say what the link is: View source on GitHub.
Then we can have a second paragraph underneath, which includes a link to the new contribution guideline that Ryan is working on.

[peterbe]

@chrisdavidmills I re-labelled the first link to something that is more "truthful". I.e. "Source on GitHub" instead of "Edit on GitHub" because simply linking to the source isn't "edit". An "Edit on GitHub" link could link to what you get after you press the little "edit pen" icon:

Simply saying "Source on GitHub" is simple, to the point, and the truth. Power-users will still know what to do with that.

Also, I took your advice and made it into a header that encompasses two links:

[peterbe]

@schalkneethling I've rearranged the HTML quite a bit here so I'm looking to you for a review on those changes. In particular; can you work with this?
I don't have any styling I want to do so there are no className="..." but I did put in an id="on-github" even though there's no #on-github { ... } in any .scss file. But I quite like having and ID on it because then you can link to the bottom section like this: http://localhost:3000/en-US/docs/MDN/Kitchensink#on-github

Can you review the resulting HTML structure?

[peterbe]

I've edited the new-issue title as per your suggestion:

[peterbe]

It looks a little bit weird, but it'll have to do.
This is what it looks like if the document title length is greater than 50 characters:

[peterbe]

I like the idea of experimenting with filling out the information on the MDN side rather than the GitHub side. Perhaps you could include a select menu containing the options for the types of problem to report in there?

If you have some suggestions for what those questions should be; we can implement it. But perhaps after this PR has landed. You know, to break it up and potentially consider it a thing to tackle post-launch.

A concern I always have is that: Suppose you (as a reader who wants to complain about the document) set side energy there and then to read through the option and think hard. And perhaps you select the "Option (please specify)" option and you think and type stuff and then you click the submit button which takes you to GitHub.com and then you realize "Crap! I have to sign in to my GitHub account now?!"
Perhaps people expect that the form will just swallow the form inputs, not expect me to do more.
So having a simple hyperlink is immediately setting the right expectations.

[peterbe]

Lastly, I think the needs triage label is useful; I'd also love to automatically generate a label pertaining to the type of content it relates to, so for example if it is under /Web/API, you get a label of "Content:WebAPI", if it is under CSS you get a label of "Content:CSS", etc.

The content areas we need to have different labes for (imo) are HTML, CSS, JavaScript, WebAPI, WebExt, DevTools, A11y, HTTP, Learn, and Other for anything else.

I made it so that it always includes the label needs triage. But note, that actually doesn't exist as a label yet. But once it does, it'll be attached. That's true for all the labels actually. If there isn't a label called "Content: CSS" a new issue filed from this cool link will not get that label.

I took your advice verbatim. You can see the hardcoded list here:
1c79c99

[peterbe]

@chrisdavidmills Perhaps it's hard to review this unless you just trust the screenshots and the flood of my comments, but r?

[schalkneethling]

Two small suggestions for your review. Other than that r+w/c

[peterbe]

@chrisdavidmills @schalkneethling One thing that we should probably address before we merge this is that the header is still the old header. I.e. "Report a content problem (world map icon)" which takes to a template-picked page.

My gut tells me the first and immediate solution is to refactor the link we have here in the document-footer and use the exact same for the "Report a content problem" header. Assuming you're on a document page.

[peterbe]

@chrisdavidmills Now you can review this by testing in staging instead of having to read the git diff.
I pushed my branch to mdn and built a production site with this branch. (it'll get replaced at the next tick of a 24h cron job so get it while it's hot)

For example, scroll down to on a page like https://main.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach and take a careful look at the texts and the links and how it actually eventually appears when you file the issue.

Also, remember that the for this to fully work, we (MDN team) need to create all these labels in github.com/mdn/content to work.
For example, in this example you'll see that the URL has &labels=Content%3A+JavaScript which means we need to create a issue label on that GitHub repo called Content: JavaScript.

[chrisdavidmills]

I think this looks fabulous, great work Peter. The text itself is good, and the GitHub issue templates also look good.. The only thing I wonder is — could we encourage people to fix the bug themselves in some way that's not too obtrusive?

I'd use something like the following underneath the existing two bullets — "If you want to fix the content problem yourself, get started with our Contribution guide)."

[peterbe]

@chrisdavidmills I just copied your text suggestion verbatim. I hope it didn't have any typos.

r?

[peterbe]

@chrisdavidmills Ping for a final review.

[chrisdavidmills]

@peterbe It looks a bit too long, compared to the other two lines. Let's shorten it a bit, to

"Want to fix the problem yourself? See our Contribution guide."

[peterbe]

@chrisdavidmills Updated

[chrisdavidmills]

Looks much better, thanks @peterbe !