WordPress.org

Making WordPress.org

Opened 5 weeks ago

Last modified 5 days ago

#4915 new enhancement

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

Reported by: bph Owned by:
Milestone: Priority: normal
Component: HelpHub Keywords: needs-design
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 (4)

4915-1.patch (837 bytes) - added by milana_cap 2 weeks ago.
Add comments support for HelpHub CPT
4915-2.patch (1.3 KB) - added by milana_cap 2 weeks ago.
Support for HTML comment list and form, call comment template in single.php
4915-3.patch (1.9 KB) - added by milana_cap 2 weeks ago.
Comments template for the theme
comments.png (255.1 KB) - added by milana_cap 2 weeks ago.
Current state with code from patches.

Download all attachments as: .zip

Change History (19)

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


5 weeks ago

#2 @bph
5 weeks ago

  • Type changed from defect to enhancement

#3 @milana_cap
5 weeks 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
5 weeks 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
5 weeks 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.


2 weeks ago

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


2 weeks ago

@milana_cap
2 weeks ago

Add comments support for HelpHub CPT

@milana_cap
2 weeks ago

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

@milana_cap
2 weeks ago

Comments template for the theme

@milana_cap
2 weeks ago

Current state with code from patches.

#8 @milana_cap
2 weeks 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
7 days 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 7 days ago by bph (previous) (diff)

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


7 days ago

#11 @Marcio Zebedeu
7 days 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
5 days 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
5 days 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 5 days ago by bph (previous) (diff)

#14 @Marcio Zebedeu
5 days ago

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

#15 in reply to: ↑ 13 @milana_cap
5 days 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.

Note: See TracTickets for help on using tickets.