Page MenuHomePhabricator

Newcomer tasks: suggested edit screen in guidance
Open, Needs TriagePublic

Description

When the user first encounters the help panel after clicking a suggested edit, they will be on an article in read mode, and the panel will be displaying the "suggested edit screen". This screen will also display in edit mode. It is identical across the two modes, except for its footer. The actual written content of the screen is covered in T245786: Newcomer tasks: guidance written content.

The specifications here follow along with the corresponding prototypes. Where they differ, the written specifications take precedent:

NOTE: For redlined design specs see the Growth Zeplin board for the relevant screens tagged "Guidance v1.2"

Header and body

  • Header: the header of the panel should read "Suggested edits"
  • Header section
    • Contains the edit type, e.g. "Copyedit" or "Find references"
    • Contains the difficulty level, e.g. "Medium"
    • Contains the estimated time, e.g. "3 - 5 minutes"
    • Contains the suggested edit graphic of a pencil/ruler/lightbulb.
    • This is exact same content that is used in the task explanation widget (T235046), shown in the screenshot below.
    • This content should be displayed the exact same way in the mobile peek (see T244434).
  • Quick start tips
    • This is the only content on the panel in the first version.
    • There should be a header that reads "Quick start tips". There should not be a chevron beside that header as shown in the prototype, because there won't be other content.
    • There will be a series of tips that contain text, links, and potentially small images. The content and number of tips may need to vary between task types, platforms, languages, and editors. There will be no more than 8.
    • The tips have numbered tabs starting at 1.
    • The user can click on a tab to go to that tip.
    • The content of the tips is covered in T245786: Newcomer tasks: guidance written content.
    • The tips auto-advance every five seconds until the user has interacted with the panel in some way. Once the user interacts with the panel, the tips stay on whichever one they were on when the user interacted. This specification extends across the reading and editing experiences, i.e. if the user has not interacted with the panel in read mode, the tips should still be auto-advancing when the user gets to edit mode. This is covered in T253009
  • FAQ: in the "..." overflow menu of the panel, there is an option labeled, "Suggested edit FAQ". It will link to this page.

Footer

This is the only way in which the suggested edit screen differs between read and edit mode.

  • Read mode:
    • On mobile, the footer says, "Ready? Tap the edit pencil on the article to start."
    • On desktop, the footer says, "Ready? Click "Edit" to get started."
  • Edit mode: the footer contains a back button, which brings the user back to the root screen (see T244546: Newcomer tasks: guidance root screen). No footer (user navigates back to the root screen via the back arrow in the header)

Instrumentation

Below are the portions of our instrumentation plan that relate to this component. See T246919: Newcomer tasks: guidance instrumentation for the full plan. The work to implement this will be done in T253010

  • This screen displays on desktop when the user arrives on the article. On mobile, it displays when the user has tapped the mobile peek.
  • impression: we want to record that the user saw the help panel and which set of content it displays, in terms of which “task type” it is guiding, and whether it is showing the desktop VE, mobile VE, desktop wikitext, or mobile wikitext content.
  • clicks: we want to record exactly which tab the user clicks on when they click through the quick tips.
  • auto-advance: the quick start tabs will advance automatically every five seconds until the user clicks one. We want to record an event for each auto-advance, indicating which tab it advanced to.
  • link clicks: the suggested edit screen will contain links to help documents, to which we want to record clicks.

Related Objects

StatusSubtypeAssignedTask
OpenNone
Openkostajh
Openkostajh
OpenMMiller_WMF
ResolvedCatrope
Resolvedkostajh
ResolvedTgr
OpenTgr
OpenNone
OpenNone
OpenNone
ResolvedCatrope
ResolvedTgr
OpenBUG REPORTTgr
ResolvedTgr
Openkostajh
ResolvedTgr
ResolvedBUG REPORTCatrope
OpenNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
MMiller_WMF updated the task description. (Show Details)Feb 11 2020, 1:55 AM
MMiller_WMF updated the task description. (Show Details)
RHo updated the task description. (Show Details)Feb 24 2020, 10:05 PM
MMiller_WMF updated the task description. (Show Details)Mar 4 2020, 5:58 PM

Header: the header of the panel should read "Suggested edit"

@RHo on mobile, the mocks show "Suggested edit help" while desktop has "Suggested edit" -- should it be "Suggested edit" for both?

MMiller_WMF updated the task description. (Show Details)Apr 3 2020, 10:36 PM

@kostajh -- thanks for doing a close read and noticing the difference. Now that I'm looking at it again, I think they should both say "Suggested edits" (plural). I made that change in the task description. I think this way, the users will learn "right, this panel is about suggested edits", and that set us up better for variants where the user may receive additional suggestions from the panel.

RHo added a comment.Apr 6 2020, 7:11 PM

Hi @kostajh - I have also updated the copy in the Zeplin according to @MMiller_WMF's clarification

@MMiller_WMF @RHo I wanted to clarify something for the behavior.

When the user clicks on a suggested edit card, they arrive at the reading mode of an article on desktop and mobile. When the panel opens, they should see the suggested edits panel with the guidance tips. In the prototype, and the mockups, it looks like the help panel should be "locked" to this suggested edits panel, i.e. the user cannot click Back in the panel to go to the root screen. But after they have clicked Edit, the help panel opens at the suggested edits / guidance panel, and the user *can* then click back to get to the root screen.

Do I understand the requirements correctly? It would be simpler to allow the user to click "Back" to the root screen in all scenarios instead of locking it to suggested edits / guidance and disallowing back, but it's not a huge amount of work to implement that behavior either.

RHo added a comment.Apr 7 2020, 7:24 PM

@MMiller_WMF @RHo I wanted to clarify something for the behavior.

When the user clicks on a suggested edit card, they arrive at the reading mode of an article on desktop and mobile. When the panel opens, they should see the suggested edits panel with the guidance tips. In the prototype, and the mockups, it looks like the help panel should be "locked" to this suggested edits panel, i.e. the user cannot click Back in the panel to go to the root screen. But after they have clicked Edit, the help panel opens at the suggested edits / guidance panel, and the user *can* then click back to get to the root screen.

Do I understand the requirements correctly? It would be simpler to allow the user to click "Back" to the root screen in all scenarios instead of locking it to suggested edits / guidance and disallowing back, but it's not a huge amount of work to implement that behavior either.

Hi @kostajh - yes, your understanding is correct (the read-mode is not meant to allow users to navigate to the root screen). I can live with the amendment to allow users to go back to the root screen from read mode if that makes implementation easier. However, the important part is that the footer section on the Suggested edits screen is only shown on read-mode.

@kostajh -- this business rule of allowing users to go back to the root screen in read mode actually fits well with another rule on T244431: Newcomer tasks: guidance panel behavior, which is that the panel should remain in the same state after the user clicks Edit. i.e. if the panel was open to Quick Start tip #4 in read mode, and the user clicks edit, the panel should be open to Quick Start tip #4 in edit mode. In other words, we prefer for fewer things in the panel to change between those two moments. Here's a screenshot of the clarifying diff I put on that task:

I can live with the amendment to allow users to go back to the root screen from read mode if that makes implementation easier. However, the important part is that the footer section on the Suggested edits screen is only shown on read-mode.

Sounds good, thanks :)

FAQ: underneath the quick start tips at the bottom of the body area should be a blue link that reads, "Suggested edit FAQ" preceded by a blue lightbulb icon.

@RHo I might be missing it: is this shown in Zeplin somewhere?

which is that the panel should remain in the same state after the user clicks Edit

Sounds good @MMiller_WMF

There will be a series of tips that contain text, links, and potentially small images. The content and number of tips may need to vary between task types, platforms, languages, and editors. There will be no more than 8.

This requirement reminded me of T215911: Help panel: Manage help panel links on wiki and T211117: Help panel: provide ability to vary links by context. It might be worth taking a detour to resolve those issues so we can reuse the same tech for this task (there are some comments about this in T246939#5977311 and probably elsewhere too, I think @Tgr @Catrope and @marcella talked about this at all hands in January).

My assumption is that we will eventually allow communities to create their own types of tasks (e.g. not just copyedit, references, update etc) and therefore we'd want to allow them to make their own guidance tips for that as well. Even if we aren't concerned about that now, moving this to on-wiki configuration would allow for more rapid iteration of configuration and simplify our work in the T247507: Scale: deploy Growth features to 100 wikis project, as we won't have a bunch of complex config to add for each wiki that wants the guidance feature.

@Catrope @Tgr @MMiller_WMF thoughts?

MMiller_WMF updated the task description. (Show Details)Apr 8 2020, 5:48 PM
Tgr added a comment.Apr 8 2020, 5:57 PM

We already allow communities to create their own types of tasks; at least, I don't think there's anything preventing them from adding new task types via the task config page. I agree it would be nice to keep the tips similarly flexible.

In the future we'll hopefully make the config system better; for now, one option would be to use a message name derived from the task type name, with section headers to separate the tips (so always one message per task type). That puts some limits on what kind of formatting can be in a tip, but I don't think it will become an obstacle in practice.

for now, one option would be to use a message name derived from the task type name, with section headers to separate the tips (so always one message per task type).

I'm not sure this would work with the requirements, which are to allow text, maybe wikitext (bold formatting is in the prototype) and images, plus also the need to vary those messages based on editor and mobile/desktop. It seems to me like we need the ability to have the contents of the quickstart tips on-wiki in a configuration page rather than in translatewiki.

MMiller_WMF added a comment.EditedApr 9 2020, 5:35 PM

@kostajh @Tgr -- in general, I think it's a good thing for communities to be able to manage these sorts of configurations on-wiki. As you say, it gives them flexibility and it makes it easier to scale. I have some thoughts on this, but not decisions -- I think you should make those, but I can certainly weigh in when it comes to choices about whether we should spend more or less time on the architecting:

  • For the quick tips, I think it would be fine for communities to be able to locally override our copy for their wiki and add/subtract tips, but definitely not to do that globally. Our team is expert on how to talk to newcomers, so we are deliberate about what the messages say.
  • On-wiki configuration also appeals to me because then non-technical members of our team (e.g. @Trizek-WMF, @RHo, and me) would be able to tweak the tips without deployments. Would it be possible for there to be a global on-wiki configuration that can be overridden by local ones?
  • Also, we have written the guidance content to apply only to the Visual Editor, because we think newcomers will have a better experience in that editor and because it is more straightforward to describe to newcomers how to be successful with their first edit. But some wikis may prefer to nudge newcomers toward wikitext editors instead, and we'll want them to be able to configure guidance content for those editors.
  • In terms of new task types, I think communities could potentially create new task types in the farther future, but I do not see this happening in the next year. We haven't heard any ideas like this from communities so far, and most of the experienced users are only aware of newcomer tasks when they see them in the Recent Changes feed or Watchlist. So I don't think we should do additional work in the near term solely geared toward allowing communities to develop new task types.
  • I posted the actual guidance content yesterday on T245786: Newcomer tasks: guidance written content, so you'll be able to see what kind of formatting we need, and hopefully that detail will make it clear how we should proceed.

How does this sound?

Tgr added a comment.Apr 11 2020, 12:03 PM

I'm not sure this would work with the requirements, which are to allow text, maybe wikitext (bold formatting is in the prototype) and images

Those would still work with messages (although images would have to go through Commons which is a slight bit of extra effort).

plus also the need to vary those messages based on editor and mobile/desktop.

Maybe have four different messages then?

It seems to me like we need the ability to have the contents of the quickstart tips on-wiki in a configuration page rather than in translatewiki.

They could be easily added to the task configuration page, but it doesn't make varying on editor/device any easier, doesn't mean raw HTML content any more safe (at least messages can be limited to interface admins via $wgRawHtmlMessages), it's a particularly unfriendly UI for editing text (\n, quote mark escaping, lack of previews...), and there is no easy way for us to track whether translations or translations updates are done.

Would it be possible for there to be a global on-wiki configuration that can be overridden by local ones?

We'd have to put some thought into what overriding actually means (we'd need a merge strategy for the global + local config, basically). But otherwise, technically possible. Having global config pages is a bit inconvenient (we cannot load them too often for performance reasons so we cannot detect immediately when they change) but the ORES topic config page is already global so not much change there.

@Tgr -- one clarification is that when I refer to "images", I'm just talking about "graphics" that we already use, like for instance this one from the intro overlay:

Does that make any difference, with respect to going through Commons?

Tgr added a comment.Apr 14 2020, 1:04 PM

Yeah, I did mean those. In hindsight though Commons was a really stupid idea. If we ended up using messages, we'd probably insert those graphics via some placeholder mechanism.

@RHo the desktop footer has "Ready?" in regular font weight while the mobile footer shows "Ready?" in bold, should it be the same font weight in both cases?

@RHo the desktop footer has "Ready?" in regular font weight while the mobile footer shows "Ready?" in bold, should it be the same font weight in both cases?

@RHo / @MMiller_WMF

Also the mobile one has a period at the end while desktop does not, should they both have a period?

Another question:

If the user has already been through guidance once and clicked Edit, they don't get the blue pulsating dot. In theory that means they know the Edit button is up at the top, but still, it's basically all the way on the other side of the screen from where they are reading "Click Edit on the article". So, two questions:

  • should we maybe link the word "Edit" to open the editor when clicked?
  • rather than Click Edit on the article ... should we be more specific and say Click "Edit" at the top of the article ...?

Change 589590 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] (wip) Help panel: Add footer for suggested edits guidance

https://gerrit.wikimedia.org/r/589590

Edit mode: the footer contains a back button, which brings the user back to the root screen (see T244546: Newcomer tasks: guidance root screen).

@RHo / @MMiller_WMF given the work done in T248065, I assume that the footer should not contain a back button when in edit mode. Instead, we could just not have the footer, or show different footer text. Thoughts?

@kostajh -- I can answer one of these questions. The rest are for @RHo.

If the user has already been through guidance once and clicked Edit, they don't get the blue pulsating dot. In theory that means they know the Edit button is up at the top, but still, it's basically all the way on the other side of the screen from where they are reading "Click Edit on the article". So, two questions:

  • should we maybe link the word "Edit" to open the editor when clicked?
  • rather than Click Edit on the article ... should we be more specific and say Click "Edit" at the top of the article ...?

We don't want them to be able to click edit from the help panel, because we want them to learn in that moment how to click edit in general, even when the help panel isn't around. And we think that if they've already been through the process once and seen the blue dot, they'll know where to find "Edit". I do think the text could be clearer -- but only with more length, and I'm worried that adding something like "at the top of the article" will make the sentence super long in some of the longer languages. What do you think?

RHo added a comment.EditedApr 17 2020, 5:36 PM

@RHo the desktop footer has "Ready?" in regular font weight while the mobile footer shows "Ready?" in bold, should it be the same font weight in both cases?

Apologies @kostajh - it should be "Ready?" in bold on desktop as with mobile. I've updated the Zeplin.
Also the copy should be the same in both, so added a period on the end of Desktop too.

RHo added a comment.Apr 17 2020, 5:37 PM

Edit mode: the footer contains a back button, which brings the user back to the root screen (see T244546: Newcomer tasks: guidance root screen).

@RHo / @MMiller_WMF given the work done in T248065, I assume that the footer should not contain a back button when in edit mode. Instead, we could just not have the footer, or show different footer text. Thoughts?

Correct - there is no longer a footer in edit mode now due to changes (improvements!) in T248065. I will update the description.

RHo updated the task description. (Show Details)Apr 17 2020, 5:39 PM

We don't want them to be able to click edit from the help panel, because we want them to learn in that moment how to click edit in general, even when the help panel isn't around. And we think that if they've already been through the process once and seen the blue dot, they'll know where to find "Edit". I do think the text could be clearer -- but only with more length, and I'm worried that adding something like "at the top of the article" will make the sentence super long in some of the longer languages. What do you think?

Yeah, nevermind, I'd agree that with the blue dot it's going to be pretty clear. I think it just stood out to me because I was looking at the page on a big monitor, without the blue dot (since I'd already clicked Edit once before), and the distance between the suggestion to click edit and the location of the edit button seemed vast.

Change 589590 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel: Add footer for suggested edits guidance

https://gerrit.wikimedia.org/r/589590

Change 593062 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] (wip) quick start tips

https://gerrit.wikimedia.org/r/593062

Change 596803 had a related patch set uploaded (by Catrope; owner: Catrope):
[mediawiki/extensions/GrowthExperiments@master] Help panel: Open automatically in guidance mode

https://gerrit.wikimedia.org/r/596803

Change 596803 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel: Open automatically in guidance mode

https://gerrit.wikimedia.org/r/596803

Change 598455 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] (wip) Refactor help panel tips

https://gerrit.wikimedia.org/r/598455

Change 593062 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel: Add quick start tips to guidance

https://gerrit.wikimedia.org/r/593062

Change 598508 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] Help panel tips: Fix parameter number in i18n

https://gerrit.wikimedia.org/r/598508

Change 598508 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel tips: Fix parameter number in i18n

https://gerrit.wikimedia.org/r/598508

Change 598527 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] Help panel tips: Use names instead of numbers for steps

https://gerrit.wikimedia.org/r/598527

Change 598527 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel tips: Use names instead of numbers for steps

https://gerrit.wikimedia.org/r/598527

Change 598455 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Refactor help panel tips

https://gerrit.wikimedia.org/r/598455

FAQ: in the "..." overflow menu of the panel, there is an option labeled, "Suggested edit FAQ". It will link to this page.

@MMiller_WMF should it be "Suggested edit" or "Suggested edits"? Elsewhere in the UI (homepage, help panel title) we use the plural form.

Change 602065 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] Help panel guidance: Add suggested edits FAQ link

https://gerrit.wikimedia.org/r/602065

kostajh updated the task description. (Show Details)Jun 3 2020, 12:20 PM

This has one item in code review (the FAQ link), and then the auto advancing and instrumentation tasks can be managed in their subtasks (updated the description to reference those specifically in T244541#6188505), so after code review this task could go to QA.

FAQ: in the "..." overflow menu of the panel, there is an option labeled, "Suggested edit FAQ". It will link to this page.

@MMiller_WMF should it be "Suggested edit" or "Suggested edits"? Elsewhere in the UI (homepage, help panel title) we use the plural form.

For now I've gone with "Suggested edits FAQ" in the patch and also as the link-id for instrumentation (suggested-edits-faq), but can update these if you'd like.

@kostajh -- the plural is fine. Thank you.

Change 602065 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel guidance: Add suggested edits FAQ link

https://gerrit.wikimedia.org/r/602065

Change 602150 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/GrowthExperiments@master] Help panel guidance: Remove copyedit icon

https://gerrit.wikimedia.org/r/602150

Change 602150 merged by jenkins-bot:
[mediawiki/extensions/GrowthExperiments@master] Help panel guidance: Remove copyedit graphic

https://gerrit.wikimedia.org/r/602150

Etonkovidova updated the task description. (Show Details)Jun 4 2020, 9:06 PM

Moving to Design review - the check marks in the task description indicate that the majority of specs are in place.

(1) As per @kostajh comment

[...] the auto advancing and instrumentation tasks can be managed in their subtasks (updated the description to reference those specifically

(2) The only concern is about accessibility (the contrast ratio) for

.oo-ui-buttonElement.oo-ui-widget-enabled > .oo-ui-buttonElement-button > .oo-ui-iconElement-icon:not(.oo-ui-image-invert), .oo-ui-buttonElement.oo-ui-widget-enabled > .oo-ui-buttonElement-button > .oo-ui-indicatorElement-indicator:not(.oo-ui-image-invert) {
    opacity: 0.87;

I couldn't obtain the Web tool Accessibility data for the contrast ratio (the tool doesn't work where there is background-image ) but comparing with the mockup, the 'x', three-dots, and the back arrow look paler in betalabs implementation:

mockupbetalabs
Etonkovidova added a comment.EditedJun 5 2020, 12:38 AM

Filed T254539: [mobile] cswiki - "suggested-edits-difficulty-indicator-medium" displayed on two lines

There is another deviation from the mobile mockup. It is not reproducible in the browsers emulators- the screenshot below is for iPhone 6s iOS 13.3.1 - the white space is displayed between the title and the subheader:

@RHo @Etonkovidova -- something to note as you review, that I noticed. There is a line under the header of the help panel that is not present on this screen but is present on other panel screens:



@RHo -- another note is whether you think the layout of these little icons could be improved. This is tip 6 for adding references.

RHo added a comment.Thu, Jun 18, 12:57 PM

@RHo -- another note is whether you think the layout of these little icons could be improved. This is tip 6 for adding references.

Yes, this should be addressed as part of T254527

RHo added a comment.Thu, Jun 18, 12:57 PM

@RHo @Etonkovidova -- something to note as you review, that I noticed. There is a line under the header of the help panel that is not present on this screen but is present on other panel screens:



That is intended

Thanks @Etonkovidova - I'm moving to PM review and opening a few new tasks per your review.

[...]
(2) The only concern is about accessibility (the contrast ratio) for

.oo-ui-buttonElement.oo-ui-widget-enabled > .oo-ui-buttonElement-button > .oo-ui-iconElement-icon:not(.oo-ui-image-invert), .oo-ui-buttonElement.oo-ui-widget-enabled > .oo-ui-buttonElement-button > .oo-ui-indicatorElement-indicator:not(.oo-ui-image-invert) {
    opacity: 0.87;

I couldn't obtain the Web tool Accessibility data for the contrast ratio (the tool doesn't work where there is background-image ) but comparing with the mockup, the 'x', three-dots, and the back arrow look paler in betalabs implementation:

mockupbetalabs

This is indeed not up even AA compliant contrast, which appears to be due to an additional opacity:0.5 added on top of the expected `opacity: .87' on the #000 icon. Filed T255773

There is another deviation from the mobile mockup. It is not reproducible in the browsers emulators- the screenshot below is for iPhone 6s iOS 13.3.1 - the white space is displayed between the title and the subheader:

Filed T255774.
I also filed T255770 as a regression since our previous review, not sure if related to this issue.