Add comment or feedback section to End User Documentation page for low-friction interaction

[bph]

This is a follow-up of an ​/ idea posted on the #docs p2 (make blog)
Use Case
End User documentation, especially about the block editor, is not always the most current. To get through the backlog faster, we could use help from people stopping by at the pages and give us feedback.

Most users just want to find out how things work and then move on, they might not fill out a trac ticket or add a card to a trello board. A box below the page that prompts a reader to help us with additional comment would be the easiest to leave a helpful note about missing or incorrect items.

Implementation ideas

1) Allow Comments, but make them always moderated
Moderator decision:

• approved/published, if helpful to the next reader. Rolled into documentation update work flow, with lesser priority.
• rejected, but rolled into the queue of upcoming documentation update workflow, with higher priority, and a note to the commenter via email

2) Feedback form (jetpack) see 1) without the publishing part. This had the advantage we could asked additional questions, like primary WordPress usage or something.

Additional thoughts

An advantage of a low-friction feedback loop is also that we will be able to measure how many people are connecting with the end user documentation and we learn from instant feedback to adjust our priorities.

One concern came up in today's #docs meeting: "We need to make sure user don't asked support questions and know what we are looking for".
We could offset this by adding: "Please use this form to notify us about missing or incorrect information. For support for your site, please use the support forums." (added link) (would need copy tag)

We need to be able to edit the section above the form (comment or feedback) to update the wording, while testing until we settle to the final wording... (could be a reusable block)

Some Documentation page don't need the comment/feedback section to the page owner should be able to check/uncheck the comment/feedback information....

[milana_cap]

I like the idea of possibility to leave feedback exactly where you spot the error. The more places you have to go to - the lesser chance you're going to leave feedback. So the simplicity is crucial here.

I wouldn't go with Jetpack feedback form because implementation would take a lot of time, much more than adding support to CPT (to add form/reusable block to each article) and connection between comments and posts is much more intuitive for what we need.

Comments can be turned off/on per post so that's solved as well.

Comments functionality can be implemented very quickly, with custom wording as well. In fact, I'd rather add sidebar area to the post template and then keep the content inside of widget, than adding reusable block to every post.

Another thing we need to check is how will this effect HelpHub plugin on Rosetta sites. It would be great to get some input on this from #meta team (@sergey, @netweb, @tellyworth, @obenland)

[netweb]

There's some good discussions in the below tickets already and DevHub, HelpHub, and Handbooks have a lot in common with each other.

Related:

• #658 Internationalization DevHub
• #981 Create feedback form for devhub
• #4831 Leave a comment on devhub

[bph]

The process on developer.wordpress.org seems to be a tad too elaborate for End User documentation (HelpHub) feedback.

Results in a ​post like this

@netweb thanks for digging up the other issues! Here is a summary of the references from there.

#658 mentions comments for DevHub, but not HelpHub.

`Some possibility to add comments in your own language
I think this should be done the same way as the theme and plugin directory, so we could have nl.developer.wordpress.org that is a dutch version of DevHub. I don't know what this entails for the meta team.`

It also raises of course, translations. I am not familiar how HelpHub articles are handled on the local sites/other languages and if that has any ramification on how we solve the feedback solicitation for the support articles.

#981 seems to cover also feedback for DevHub, probably in opposite to the contribution notes/form displayed above. It also mentioned that Handbook pages will have comment form enabled.

"Comments won't be publicly visible, only used as a means to submit feedback about the page to the site admins. We'll probably want to build filters into the backend so moderators can see the feedback for a particular handbook."

#4831 is pretty much the same issue for DevHub and the author comments:

"On devhub, to leave a comment to explain a function or something, we have to click on a link which will open a comment form. I think devhub would have more comment if the form was directly open."

So, it seems comments could be the way to go.

[milana_cap]

Add comments support for HelpHub CPT

[milana_cap]

Support for HTML comment list and form, call comment template in single.php

[milana_cap]

Comments template for the theme

[milana_cap]

Current state with code from patches.

[milana_cap]

@bph I added basic code for comments in patches. Screenshot shows the result. We can go from here and define wording, positioning and then ask for designs from @estelaris

[bph]

Instead of "Leave a Reply" - we could prefix the comment section with

"Find an error or is something missing? Let us know! " and then in the flow text:

"We appreciate your help reporting an issue. We'll fix things with the next update. Note: The comment will not be published and we asked for your email address someone from the documentation team members can contact you for follow-up, if necessary."

Would that work?

[Marcio Zebedeu]

I think it should be removed the fields present and the form should be available only for users with an account in WordPess. It'd be interesting to me if it looked like p2.

[marybaum]

"Find an error or is something missing? Let us know! " and then in the flow text:
"We appreciate your help reporting an issue. We'll fix things with the next update. Note: The comment will not be published and we asked for your email address someone from the documentation team members can contact you for follow-up, if necessary."

Would that work?

How bout:

Did this work the way you thought it would? Something missing, or off?
Now you can let us know right here.

Comments you enter in this field will go only to the folks who can fix it and will NOT be public. We do ask for your email in case the documentation team has questions or would like followup feedback. But that too will stay behind the scenes.

The issues you surface here will get fixed in the next update -- and will help make everyone's experience better overall.

Thanks in advance for letting the team know what you found!

[bph]

Thank you @marybaum appreciate the word-smithin here. It reads very nicely and informs the person sending in information.

@marcio-zebedeu - I am conflicted in this, and when in doubt, I tend to make a system like that more open. For this one goal would be to get users who use our documentation to tell us if it helps, and read their suggestions on what could be better. They are right there, especially if they are in a state of frustration, we give them a way to express it right there.
I fear, if a user has to create an account on WordPress.org before they can communicate, we might just save ourselves this work and guide everyone to trac or github to report issues. I feel, we could run this as an experiment, we still have a few processes to work out, but I rather make it open and learn...

@milana_cap is this the moment we can ask @estelaris for a design and add the label?

[Marcio Zebedeu]

@bph I agree with you. Your idea sounds good.

[milana_cap]

Replying to bph:

@milana_cap is this the moment we can ask @estelaris for a design and add the label?

Yes, I think we can start with design.

[estelaris]

comment section for user documentation

[estelaris]

That is a first draft based on the feedback posted here.

[theMikeD]

The form language goes to great lengths to ensure that the submitter knows that their comment will be kept private. It also tells the user why we collect their email address. All good.

But the website section seems to be just...there. There is no mention of why we collect the web address, and since the submission is kept private there is no backlink value to the user. So I'm wondering if we use this for something I'm unaware of? If there isn't, I'd suggest pulling it.

[bph]

@estelaris That's a great first iteration. Thank you! This looks like a very low-friction feedback collection form.

I also agree with @theMikeD - we don't need to collect the website from the user.

[milana_cap]

I would have two things at the bottom of every article:

1. "Was this article helpful?" (this is specifically about the content in whole, amount of useful information, existence of all steps etc)

• Yes - does nothing on frontend, it's just for us
• No - opens textarea and maybe multi-select with "I couldn't get the same result" or something similar

2. "I found a problem/error" (this is about one or more specific errors found in content)

When clicked on we show multi-select of the specific options ( "Screenshots are outdated/incorrect", "Examples are wrong", "There's a typo" ..) and text area for further explanation.

We could add descriptions for both so it's clear what is used for what.

I also like something like this little widget for linking to forums. We could perhaps have custom links to specific topics in forums.

[SergeyBiryukov]

Related: #5007

[estelaris]

The simplified form without the website

[estelaris]

This is a second option that can give the user better ideas on what to comment on, there is also a blank space for other comments

[theMikeD]

Some minor suggestions, all IMHO of course! :)

1. Documentation doesn't "work" :) Maybe "Did you find what you were looking for? "
2. Second sentence is incomplete. Try "Is something missing, or off?"
3. Third sentence implies that the reporter had noticed there was no way to submit issues previously. Is this the case? Regardless, saying so doesn't add anything meaningful; Try simplifying to "Let us know right here."
4. "Comments you send to us will go..." is a bit more friendly sounding to me.
5. "Surface" is lingo. Try "Raise" or "Found," like "The issue you found will..."
6. We dropped the website, so drop that from the Save checkbox too :)

[bph]

Wow! Thank you, Estela! (@estelaris) This looks amazing. And thank for all the patience you have thinking this through.

Although I like how the second more elaborate version, looks and feels, it might just be a step too complicated as the first version.
My observations

• The helpful/not helpful is only actionable when 'not helpful". I wouldn't want to hide the comment form. It might have some statistical value, if we can say: We had 1,500 people visit the page, 20 clicked on "helpful" 10 clicked on not helpful. We don't know what the other 1,470 people think. We can assume they are also in the "helpful", but there is not actionable value.

In essence, it's a goal to connect with users, who find the content on the page 'not helpful', in a meaning full way about why it wasn't helpful. I rather not assume anything about the silent majority.

• I am sure plenty of people would just want to check things, and not write anything. I would be one of them. Offering pre-set 'failures' would take care of those group. Great suggestions @milana_cap and @theMikeD. If we want a visitor leave us a note, there are plenty of reasons, why the documentation might not have been helpful. Reducing it to 3 options part, feels a bit prematurely to me. We don't know anything yet. I would like to gather real information before we put words into people's mouth.

I have been involved in building software one way or other for a while now, and it has been proven to me over and over again, that my assumptions about how end users feel and think are wrong the first time around. I rather would like to listen first before making assumptions.

Given the above, I would like to try it with first & plain version. Collect some data for 3 to four months and then see if we can add additional choices to the list of fly-by click reporting.

For the implementation:

• We would need this form to hooked up the overall .org spam filtering tools
• The comments are not to be public (already mentioned)
• Should have an enable/disable switch on a page/article level (as not every author or would be ready to handle feedback, yet)

Feedback handling

• These are comments, they will be accessible through the WP-Admin, and have a reply feature, every comment should have a short reply to "Thank you for your comments, we will review etc. "
• Block editor end user documentation project is managed on Trello with each page having it's own card.
• When an issue come in it will be evaluated, and put into the queue:
• typos are fixed asap (as soon as possible)
• other changes will be added as a to-do-item on the page card and priority will be moved up for an update.
• If possible the feedback person will receive another notification that the reported issue is fixed with an expression of gratefulness,

Pilot Project
During the pilot project, I will keep track of how many feedback reports, on how many pages we get and categorize the reason(s) in a weekly report.

Going with the 'simple' comment form would also have an added value that it uses existing code base, with slight modifications on the copy, so the burden on contributors seems to be less than the other variation.

I might be completely wrong about the whole thing, though. As always, I am ready to disagree and commit.

[michaelarestad]

I attempted to simplify the preface to the comment form. I modified the heading and following copy. I also am suggesting an alternate heading that is a bit shorter.

HEADING: Did you find what you were looking for? Is something missing or wrong? Let us know right here.

ALTERNATE HEADING: Was this article helpful? How could it be improved?

Feedback you send to us will go to the folks who maintain this documentation. Your email is necessary in case the team has questions or would like to follow up.

.

I also suggest removal of the following:

The issue you found will get fixed in the next update...

A statement like this can come across as a promise by setting user expectations that a change will be made in the near future. If the documentation isn't updated shortly, the user may become aggravated.

.
Could the following statement be removed in favor of showing a thank you when the user submits their feedback?

Thanks in advance for letting the team know what you found!

[netweb]

Great to see this ticket moving forward 💯

As I've highlighted in this ticket and elsewhere many sub-sites of w.org can benefit from a feedback form, DevHub already has this, this is for HelpHub, handbooks and I'm sure there are more places this would be valuable.

Moving forward it would be great to iterate on the patches from @milana_cap, the below files are pretty similar to the patches already submitted here BTW, props @milana_cap :)

Here's the DevHub feedback form in action:

​https://developer.wordpress.org/reference/functions/wp_get_post_parent_id/#user-contributed-notes

The code for this is primarily here:

https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/comments.php

https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/comments-edit.php

https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer?order=name

We can probably start by adding a HelpHub version of that here

In my mind it would be great to architect that out of the wporg-developer theme and into a shared plugin that can be used for both sites and any new sites in the future. This would help the meta team by having one common plugin to maintain instead of many similar versions

[estelaris]

After several revisions and comments. This version is ready.

[estelaris]

There was a typo on the previous form

[milana_cap]

I added another patch as per latest design.

The form is not visible to logged out visitors but I have included text and link to login so that people know they have this option.

[bph]

This is amazing. Exactly what we need. Thank you @milana_cap for the patch!

[coreymckrill]

4915-5.patch is an update to the last iteration that simplifies the comment form template a little bit and prevents comments from being exposed via the REST API (since they are supposed to be private). There's also 4915-helphub.patch, which enables support for comments on the Articles CPT.

@bph

These are comments, they will be accessible through the WP-Admin, and have a reply feature, every comment should have a short reply to "Thank you for your comments, we will review etc. "

Replying to a comment doesn't trigger an email notification to the submitter, so the reply would never be seen. If there needs to be a back-and-forth with the feedback submitter, it will probably all need to be done over email. For this first version, what if we just show a message like "Thanks for your feedback" after someone submits the comment form?

[bph]

@coreymckrill Thanks for taking is over!

Regarding comments, I think that's fine. "Thank you for your comments. We will review is quickly and review this page."

We'll learn how to handle the emails, and deal with them separately should this be an issue.

[coreymckrill]

In 10412:

Support theme: Enable feedback comments on HelpHub articles

Adds a comment form to the bottom of HelpHub articles that have enabled
comments, intended as a feedback mechanism for the content of the articles.
These comments, once submitted, can be reviewed by site admins, but are never
shown publicly. This also tweaks the comments-related REST API endpoints so that
they don't expose these feedback submissions.

Props milana_cap, coreymckrill
Fixes #4915

[coreymckrill]

@bph The above commit should enable this functionality, but each HelpHub article will still need to be updated in the "Discussion" section to enable comments.

[bph]

That's wonderful! Thank you so much @coreymckrill and @milana_cap - This is a great contribution to open up communication with visitor. Hopefully, we get important feedback from our documentation pages. I'll test this later this week.

[bph]

I enabled via "Allow comments" on this page.
​https://wordpress.org/support/article/wordpress-editor/

It would be helpful, if we could add a section for non-logged in users. to let them know they could leave a feedback if they logged in.
@milana_cap suggested [a bigger section.](https://meta.trac.wordpress.org/ticket/4915#comment:30)

It might just be enough to have "Please log in to leave a feedback" with login to link to then login page. @coreymckrill is there a way you could add that to the feedback section, please?

I reopen this for this tweak. Or would it be better to create new trac ticket?

[milana_cap]

Replying to bph:

I enabled via "Allow comments" on this page.
​https://wordpress.org/support/article/wordpress-editor/

It would be helpful, if we could add a section for non-logged in users. to let them know they could leave a feedback if they logged in.
@milana_cap suggested [a bigger section.](https://meta.trac.wordpress.org/ticket/4915#comment:30)

It might just be enough to have "Please log in to leave a feedback" with login to link to then login page. @coreymckrill is there a way you could add that to the feedback section, please?

I reopen this for this tweak. Or would it be better to create new trac ticket?

The section is there @bph , below Changelog.

[bph]

That's really odd. That it didn't show on my computer. Must have been a cache thing. Tried different browser and computer and I see it now too.
That's for watching over me @milana_cap Apologies for the additional noise.