WordPress.org

Making WordPress.org

Opened 9 months ago

Last modified 10 days ago

#4915 reviewing enhancement

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

Reported by: bph Owned by: tellyworth
Milestone: Priority: normal
Component: HelpHub Keywords: has-patch needs-testing
Cc:

Description

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....

Attachments (12)

4915-1.patch (837 bytes) - added by milana_cap 9 months ago.
Add comments support for HelpHub CPT
4915-2.patch (1.3 KB) - added by milana_cap 9 months ago.
Support for HTML comment list and form, call comment template in single.php
4915-3.patch (1.9 KB) - added by milana_cap 9 months ago.
Comments template for the theme
comments.png (255.1 KB) - added by milana_cap 9 months ago.
Current state with code from patches.
Comment Section.jpg (166.1 KB) - added by estelaris 8 months ago.
comment section for user documentation
Comment Section.2.jpg (161.2 KB) - added by estelaris 8 months ago.
The simplified form without the website
Comment Section combined.png (191.1 KB) - added by estelaris 8 months ago.
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
Comment Section.3.jpg (161.7 KB) - added by estelaris 8 months ago.
After several revisions and comments. This version is ready.
Comment Section.4.jpg (160.1 KB) - added by estelaris 8 months ago.
There was a typo on the previous form
4915-4.patch (5.0 KB) - added by milana_cap 5 weeks ago.
feedback-loggedin.png (120.4 KB) - added by milana_cap 5 weeks ago.
feedback-loggedout.png (109.0 KB) - added by milana_cap 5 weeks ago.

Download all attachments as: .zip

Change History (50)

This ticket was mentioned in Slack in #docs by bph. View the logs.


9 months ago

#2 @bph
9 months ago

  • Type changed from defect to enhancement

#3 @milana_cap
9 months ago

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)

#4 @netweb
9 months ago

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

#5 @bph
9 months ago

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

http://www.wpswfl.org/wp-content/uploads/2019/12/Screen-Shot-2019-12-18-at-3.09.32-PM.png

Results in a post like this

http://www.wpswfl.org/wp-content/uploads/2019/12/Screen-Shot-2019-12-18-at-3.29.12-PM.png

@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.

This ticket was mentioned in Slack in #docs by bph. View the logs.


9 months ago

This ticket was mentioned in Slack in #docs by aurooba. View the logs.


9 months ago

@milana_cap
9 months ago

Add comments support for HelpHub CPT

@milana_cap
9 months ago

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

@milana_cap
9 months ago

Comments template for the theme

@milana_cap
9 months ago

Current state with code from patches.

#8 @milana_cap
9 months ago

@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

#9 @bph
8 months ago

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?

Last edited 8 months ago by bph (previous) (diff)

This ticket was mentioned in Slack in #docs by bph. View the logs.


8 months ago

#11 @Marcio Zebedeu
8 months ago

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.

#12 @marybaum
8 months ago

"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!

#13 follow-up: @bph
8 months ago

  • Keywords needs-design added

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 read 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?

Last edited 8 months ago by bph (previous) (diff)

#14 @Marcio Zebedeu
8 months ago

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

#15 in reply to: ↑ 13 @milana_cap
8 months ago

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
8 months ago

comment section for user documentation

#16 @estelaris
8 months ago

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

This ticket was mentioned in Slack in #docs by bph. View the logs.


8 months ago

#18 @theMikeD
8 months ago

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.

Last edited 8 months ago by theMikeD (previous) (diff)

#19 @bph
8 months ago

@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.

#20 @milana_cap
8 months ago

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.

https://nimbusweb.me/box/attachment/3818316/tbfyskavedournsomtzl/tc5WxuTIUOJBrvLa/screenshot-confluence.atlassian.com-2020.02.04-12_36_55.png

@estelaris
8 months ago

The simplified form without the website

@estelaris
8 months ago

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

#22 @theMikeD
8 months ago

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 :)

#23 @bph
8 months ago

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.

This ticket was mentioned in Slack in #design by estelaris. View the logs.


8 months ago

#25 @michaelarestad
8 months ago

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!

#26 @netweb
8 months ago

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
8 months ago

After several revisions and comments. This version is ready.

@estelaris
8 months ago

There was a typo on the previous form

#27 @estelaris
8 months ago

  • Keywords needs-patch dev-feedback added; needs-design removed

This ticket was mentioned in Slack in #meta by bph. View the logs.


7 weeks ago

This ticket was mentioned in Slack in #docs by bph. View the logs.


5 weeks ago

@milana_cap
5 weeks ago

#30 @milana_cap
5 weeks ago

I added another patch as per latest design.

https://meta.trac.wordpress.org/attachment/ticket/4915/feedback-loggedin.png

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.

https://meta.trac.wordpress.org/attachment/ticket/4915/feedback-loggedout.png

#31 @bph
4 weeks ago

  • Keywords has-patch added; needs-patch removed

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

Last edited 4 weeks ago by bph (previous) (diff)

This ticket was mentioned in Slack in #docs by zzap. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #meta by bph. View the logs.


4 weeks ago

This ticket was mentioned in Slack in #meta by bph. View the logs.


3 weeks ago

#35 @tellyworth
3 weeks ago

  • Owner set to tellyworth
  • Status changed from new to reviewing

This ticket was mentioned in Slack in #docs by zzap. View the logs.


3 weeks ago

This ticket was mentioned in Slack in #meta by bph. View the logs.


10 days ago

#38 @tellyworth
10 days ago

  • Keywords needs-testing added; dev-feedback removed
Note: See TracTickets for help on using tickets.