Page MenuHomePhabricator

Newcomer tasks: guidance written content
Open, Needs TriagePublic

Description

In this task, we write and translate the "quick start tips" content that goes inside the suggested edit screen for guidance: T244541: Newcomer tasks: suggested edit screen in guidance

The content is in this spreadsheet: https://docs.google.com/spreadsheets/d/1qrFFQ1TbNUwn_Efwj9TB4uurv_HyksHKnXn9gH3ppew/edit?ts=5e508718#gid=0

Here's how it works:

  • For each of our five task types, the sheet lists each quick start tip in a separate row.
  • Tip number: each task type has 6 tips, except "References", which has 7.
  • Tip role: this column column is just for us to keep track of what the point of that tip is -- this is not for translating or showing to the user.
  • Desktop text: this is the main text that should be shown in the tip.
  • Mobile text (if different): in most cases, the mobile text can be the same as the desktop text, but this column contains a value if it should be different.
  • Supplement: this is illustrative content that should be below the main text in the panel. This can take several forms:
    • Text with formatting: in these cases, there is some translatable text, along with highlighting applied to part of the text, which serves to illustrate the kind of edit the tip is talking about.
    • Caption: sometimes we want to include a small, italicized caption under the the supplement.
    • Icon: this is when we want to just display a large version of some icon that we're asking the user to click on, like the "cite" icon.
    • Link: this is when we want some part of the main text to be a hyperlink. For the links that are on the final quick tip for each task type (about "learning more"), we should follow the same logic and links as we did with the task explanation widget from T235046: Newcomer tasks: task explanation widget. If a wiki has a link available for a given task type, then the line with the link in it should show up in the quick tip. If it does not have a link, it should not even have the line. For cells in the spreadsheet like F25 and F31, the link in the text should likewise only be made if the wiki has a link for that type of task. And although T235046 only shows our four target wikis, this would naturally apply to the other wikis that have newcomer tasks, and whichever links they have along with their task explanation widgets.
    • Graphic: this is when we just display a pre-existing graphic that our designer can supply.
  • Desktop QQQ: explanation of desktop text for translators, including link to desktop prototype.
  • Mobile QQQ: explanation of mobile text for translators, including link to mobile prototype.
  • Supplement QQQ: explanation of supplement text for translators.

Note that this content is all geared toward Visual Editor on both desktop and mobile. This is because we think that newcomers will have a better experience in Visual Editor, and it is easier to describe to them how to succeed on their first edits in that interface. That said, we should set up this feature so that it is possible to also set up guidance content for wikitext editors in the future, if we work with communities that would prefer to nudge newcomers to that editor instead. Perhaps this simply means being mindful of what we name these messages.

Event Timeline

@MMiller_WMF @RHo is there any content written yet? That will help with thinking through the technical implementation.

RHo added a comment.Apr 8 2020, 1:15 PM

@MMiller_WMF @RHo is there any content written yet? That will help with thinking through the technical implementation.

Hey @kostajh - this is the copy doc but it is still a draft: https://docs.google.com/spreadsheets/d/1qrFFQ1TbNUwn_Efwj9TB4uurv_HyksHKnXn9gH3ppew/

MMiller_WMF updated the task description. (Show Details)Apr 9 2020, 5:28 AM
MMiller_WMF added subscribers: revi, PPham, Urbanecm, Dyolf77_WMF.

@RHo -- I've written up and arranged the guidance content to what I think could be a near-final state. You're welcome to read and evaluate it some more, but if not, I have two requests:

  • Could you check out my remaining comments in the spreadsheet for you? They're about graphics we can add. I think it would be ideal if you included links or keywords in the "supplement' cells with graphics (both those that currently have comments and those that have resolved comments) so that engineers can easily find the right graphics.
  • Would it be possible for you to make a mockup of what a quick start tip should look like when it has supplementary text? Like for instance, the content in the first row of the spreadsheet? I think this will help engineers get the styling right.

@kostajh -- alright, here is the guidance content! Please check out the notes in the task description about what the spreadsheet contains and whether it makes sense. Will the "supplement" content work? Will this fit into TranslateWiki? Please ask my any questions here or in chat! I have tried to be thorough and careful.

And a note on translations -- while I originally thought it would be good for the ambassadors to carefully translate in the spreadsheet, I think it's better if we prepare for scale out of the gate, since this feature should theoretically be on 15 wikis in a couple months. Therefore, I spent time writing the QQQs so that they can all be translated effectively in TranslateWiki.

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

@RHo -- pinging you about mockups for this, since it will get picked up by engineers soon. Thank you!

@kostajh -- alright, here is the guidance content! Please check out the notes in the task description about what the spreadsheet contains and whether it makes sense. Will the "supplement" content work? Will this fit into TranslateWiki? Please ask my any questions here or in chat! I have tried to be thorough and careful.

Thanks, as I work on implementing it I'll post here if I have questions or concerns.

kostajh claimed this task.Apr 17 2020, 7:01 PM

I'll claim this task since I'm working on implementing it in T244541: Newcomer tasks: suggested edit screen in guidance

RHo added a comment.EditedApr 28 2020, 8:48 PM

@kostajh @MMiller_WMF - I have added some sample tips with 'supplement' text and images in the Zeplin:

@kostajh @MMiller_WMF - I have added some sample tips with 'supplement' text and images in the Zeplin:

Nice, thanks @RHo. One question looking at the first two screenshots: does the green highlight (in the first) signify something different from the yellow highlight (in the second)? If not, could we use a single highlight color throughout? Or should the first tip, regardless of task type, always use a green highlight while subsequent tips use yellow?

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

RHo added a comment.EditedApr 28 2020, 9:20 PM

@kostajh @MMiller_WMF - I have added some sample tips with 'supplement' text and images in the Zeplin:

Nice, thanks @RHo. One question looking at the first two screenshots: does the green highlight (in the first) signify something different from the yellow highlight (in the second)? If not, could we use a single highlight color throughout? Or should the first tip, regardless of task type, always use a green highlight while subsequent tips use yellow?

Hi @kostajh - so the first is using a pale blue highlight (Accent90 in the color palette) because it's a positive action, whereas the second is an example of a negative highlight in pale red (Red90) (showing a typo or other such example error). I have gone through and added when the highlight should be which color.

However, I can make it a single highlight color instead everywhere if two different highlight colors is going to add headaches for translation and customization later on. In which case we could use a single Yellow90 highlight color like so:

RHo added a comment.Apr 29 2020, 2:14 PM

hi @kostajh - I've made a redline version with the different Supplement text and image components styles called out to help with implementation in Zeplin here, also pasted below for convenience:


@MMiller_WMF please also check and let me know if I've missed any supplement type.

@RHo we talked and everything looks great. It will be useful for us to have distinct positive and negative highlighting colors. @RHo indicated in the "Supplement" column in the spreadsheet about the highlighting colors. She just has to add one more mockup, showing the "Graphic" style supplement.

RHo added a comment.Apr 29 2020, 5:28 PM

@RHo we talked and everything looks great. It will be useful for us to have distinct positive and negative highlighting colors. @RHo indicated in the "Supplement" column in the spreadsheet about the highlighting colors. She just has to add one more mockup, showing the "Graphic" style supplement.

Thanks! I've updated to add the graphic supplement type in Zeplin

@RHo @MMiller_WMF thank you for the clarifications. So, if I can try to sum this up in terms of the translation strings needed, we will need the following for tip #1 on desktop with visualeditor for the copyedit task ({editor}-{mobile-or-desktop}-{task-type-id}-{tip-item}-{tip-step}:

  • visualeditor-desktop-copyedit-main-1
  • visualeditor-desktop-copyedit-example-1
  • visualeditor-desktop-copyedit-caption-1
  • visualeditor-desktop-copyedit-text-1

So, up to 4 translatable messages per tip?. Then those can vary for mobile, so 8 messages. I believe they are then supposed eventually be able to vary by editor (VE, wikitext, wikitext 2017), so that's 24 messages for quick start tip #1, then there can be up to 8 tips so there could be 192 quick start tip messages for each task type, so with 5 task types we will need 960 messages defined for this feature. Does that sound right?

I'm trying to think of how we can present this so it is not overwhelming to translators, especially if we want this to be part of the feature set that scales to non target wikis.

Some other comments (cc @Tgr and @Catrope for your thoughts please):

  • for tip main content, in order to support the inline icon, I guess we'd have something like this in the en.json text: "Tip main content with inline icon {{copyedit-main-inline-icon}} example", then we'd have to hope that translators leave in {{inline-icon}}, then we'd have some kind of lookup that knows to replace {{copyedit-main-inline-icon}} with the appropriate HMTL
  • for supplement example text, I was thinking we would use <mark class="postive">positive</mark> and <mark class="negative">negative</mark> and again hope that translators leave that markup in place. For the link, similar to the inline icon above, we'd need a lookup that knows to replace [[$1]] in that message with the appropriate link for that tip for mobile/desktop in that particular editor on quick start tip #1
  • supplement image and graphic examples, similar to the above we'll need some kind of lookup to know which image to add for this particular scenario
Tgr added a comment.Apr 29 2020, 8:46 PM

Translating wikitext with some HTML in it is not so rare, translators should be able to handle it. I would use that for icons/images as well (use an empty span with a class and/or data attribute, replace after the string has been inserted in the DOM), you could use normal variables but that would require tracking which message takes which variable which sounds moderately annoying. {{..}} constructs will be interpreted as templates in previews so that's unnecessarily confusing. For link, normal message variables seem to suffice.

Presumably there will be things which are not any different between mobile and desktop, or the various editors. Will there be a fallback mechanism, to avoid duplicating work for translators? How would the fallback chain be determined?

Will the number of tips be hardcoded? Or will it be in the JSON config? (That would be nice for extendability, but then the messages can't be in the ResourceLoader manifest and loading them would require an extra API call.)

@RHo @MMiller_WMF thank you for the clarifications. So, if I can try to sum this up in terms of the translation strings needed, we will need the following for tip #1 on desktop with visualeditor for the copyedit task ({editor}-{mobile-or-desktop}-{task-type-id}-{tip-item}-{tip-step}:

  • visualeditor-desktop-copyedit-main-1
  • visualeditor-desktop-copyedit-example-1
  • visualeditor-desktop-copyedit-caption-1
  • visualeditor-desktop-copyedit-text-1

So, up to 4 translatable messages per tip?. Then those can vary for mobile, so 8 messages. I believe they are then supposed eventually be able to vary by editor (VE, wikitext, wikitext 2017), so that's 24 messages for quick start tip #1, then there can be up to 8 tips so there could be 192 quick start tip messages for each task type, so with 5 task types we will need 960 messages defined for this feature. Does that sound right?

I'm trying to think of how we can present this so it is not overwhelming to translators, especially if we want this to be part of the feature set that scales to non target wikis.

We could get away with not defining messages that we know will be unused or empty (which is most of the -8s, and a lot of the captions/examples it looks like). That, and initially not defining the non-VE messages, should cut down on the translator overload a lot. You can programmatically determine whether a message exists (at least in PHP, using wfMessage( 'foo' )->exists()), so one way that we could determine that there are 7 message tips for a given task type is by just looking at which messages exist, and finding that visualeditor-desktop-copyedit-main-1 through main-7 exist, but -main-8 doesn't.

  • for tip main content, in order to support the inline icon, I guess we'd have something like this in the en.json text: "Tip main content with inline icon {{copyedit-main-inline-icon}} example", then we'd have to hope that translators leave in {{inline-icon}}, then we'd have some kind of lookup that knows to replace {{copyedit-main-inline-icon}} with the appropriate HMTL

As @Tgr said, we could just use a parameter ($1) here? Translators know what to do with those, and the qqq could explain that $1 is an icon. We could use a parameter for the reference example (<sup>[3]</sup>) as well, or alternatively that could just be left in as wikitext.

  • for supplement example text, I was thinking we would use <mark class="postive">positive</mark> and <mark class="negative">negative</mark> and again hope that translators leave that markup in place.

I think that's a great idea (better than my idea, which was to use <ins> and <del>; TIL about the <mark> tag), and as @Tgr says translators are somewhat used to seeing things like span tags in messages and will likely know to leave them in place.

For the link, similar to the inline icon above, we'd need a lookup that knows to replace [[$1]] in that message with the appropriate link for that tip for mobile/desktop in that particular editor on quick start tip #1

It sounds like we could use [[$1|text of the link]] or [$1 text of the link] here?

  • supplement image and graphic examples, similar to the above we'll need some kind of lookup to know which image to add for this particular scenario

Yeah, that's a bit tricky. I would be OK with just hard-coding that in a data structure in a JS file somewhere. We could try encoding this in the messages, and that might work for most things (like icons and the fake reference), but we'd still need special treatment for the publish button example. So on balance, I think this should just be done in the code, and be (semi-)hardcoded.

@kostajh -- thanks for thinking this through and posting. I think what you've gamed out is the high end maximum of how many messages there would be, but I think, as @Catrope says, the actual number of messages we need right now is much less. For instance, in tip #1 for copyedit, I think there are only two strings, not four. There's the main text and the example -- but there's no caption. Also, what is "text-1"? Also, given that the content is the same for mobile, do we need to get it translated twice, or is it possible to re-use?

Also, what is "text-1"?

That is "Supplement (non-example) text with link" in this image https://phabricator.wikimedia.org/F31787039

Also, given that the content is the same for mobile, do we need to get it translated twice, or is it possible to re-use?

No, we should be able to reuse.

@MMiller_WMF @RHo in the screenshot in F31787039 the first image example ("Supplement image example") has English letters in it; does this mean that we anticipate that we need to support varying the supplement images per language? Or will we use the same image regardless of what language (maybe with an RTL version for RTL languages)? Same question for the last image in that screenshot ("Supplement graphic illustration/example").

Also, could you please explain what the conceptual difference is between "Supplement image" and "Supplement graphic illustration"?

RHo added a comment.May 5 2020, 5:32 PM

@MMiller_WMF @RHo in the screenshot in F31787039 the first image example ("Supplement image example") has English letters in it; does this mean that we anticipate that we need to support varying the supplement images per language? Or will we use the same image regardless of what language (maybe with an RTL version for RTL languages)? Same question for the last image in that screenshot ("Supplement graphic illustration/example").

I believe the answer to the first question is yes, but @MMiller_WMF please confirm.

Also, could you please explain what the conceptual difference is between "Supplement image" and "Supplement graphic illustration"?

The difference between the supplement image is that these are screenshots referencing something in the UI, whereas the the graphic/illustration does not, but serves a more decorative purpose.

@kostajh -- for "supplement image example", I think the only instance we have is when we want to show the "Publish changes..." button in the last tip for each task type (e.g. cell F7 in the spreadsheet). And I was thinking maybe we could just render the "Publish changes..." button the same way the visual editor does, and therefore we wouldn't need translations there, because we already have them. Is that a possible way to do it? Or should we just draw it ourselves and translate its contents ourselves, so that we can make it look the same as the real "Publish changes..." button?

And to clarify about the graphic/illustration: the graphic/illustration has no words. They're just these graphics that we created for suggested edits, like this:


@RHo -- where can @kostajh access all those graphics?

RHo added a comment.May 6 2020, 5:23 AM

@kostajh -- for "supplement image example", I think the only instance we have is when we want to show the "Publish changes..." button in the last tip for each task type (e.g. cell F7 in the spreadsheet). And I was thinking maybe we could just render the "Publish changes..." button the same way the visual editor does, and therefore we wouldn't need translations there, because we already have them. Is that a possible way to do it? Or should we just draw it ourselves and translate its contents ourselves, so that we can make it look the same as the real "Publish changes..." button?

And to clarify about the graphic/illustration: the graphic/illustration has no words. They're just these graphics that we created for suggested edits, like this:


@RHo -- where can @kostajh access all those graphics?

I've noted where they are in the spreadsheet. See my point above as well about them being not UI images and not having text (so therefore do not need localisation, or captioning).

kostajh added a comment.EditedMay 6 2020, 10:08 AM

And I was thinking maybe we could just render the "Publish changes..." button the same way the visual editor does, and therefore we wouldn't need translations there, because we already have them. Is that a possible way to do it? Or should we just draw it ourselves and translate its contents ourselves, so that we can make it look the same as the real "Publish changes..." button?

I think we could reference the "Publish changes" message key and render a button, but this is now getting a lot more complicated, because you need to know to render the button in a certain way (with progressive, primary styling). Also, I mentioned this in a comment in Zeplin (side note: should we be Zeplin for comments?) but do you want the user to actually be able to click "Publish changes" and have that function, or will clicking on that be a no-op and they have to know to click the real Publish Changes button elsewhere on the page. If we want it to actually "Publish changes", we should talk because that will add a lot more complexity. If we don't want it to publish the changes, then will we confuse users?

I've noted where they are in the spreadsheet. See my point above as well about them being not UI images and not having text (so therefore do not need localisation, or captioning).

I think we will need wording to describe what these images are, for assistive text for accessibility purposes. (Edit: Not sure about this, if they are purely decorative then I think it's probably OK to not have assistive text but if they convey meaning then we should add the text.)


Overall, I wonder if we could step back for a minute to define what each individual tip component can look like and how it should function (as well as how they all function together). Maybe this could be a good use case for us to try out Storybook.

RHo added a comment.May 6 2020, 12:04 PM

I think we will need wording to describe what these images are, for assistive text for accessibility purposes. (Edit: Not sure about this, if they are purely decorative then I think it's probably OK to not have assistive text but if they convey meaning then we should add the text.)

Agree that alt text on these images makes sense, but wanted to confirm you this and not visible caption text?


Overall, I wonder if we could step back for a minute to define what each individual tip component can look like and how it should function (as well as how they all function together). Maybe this could be a good use case for us to try out Storybook.

My attempt to do this (define tip components) was in this mock:

hi @kostajh - I've made a redline version with the different Supplement text and image components styles called out to help with implementation in Zeplin here, also pasted below for convenience:

@kostajh -- the intention is not for it to be an actual button that publishes changes, or an actual button at all. It's really just meant to be a picture of a button, and the user is meant to see it and then find the real version in the editor, and then click that. But it sounds like this will probably be more trouble than it's worth. So let's do away with this supplement in the tip, and just have text. I went through and changed the relevant rows in the spreadsheet (rows 7, 13, 20, 26, and 32) to remove this button. I changed the text for desktop and mobile in those rows to explain it instead. How does this sound?

@RHo -- what do you think the alt-text should be on the graphics? I'm having trouble thinking of what they should be -- I think the images are purely decorative.

RHo added a comment.May 7 2020, 8:40 AM

@RHo -- what do you think the alt-text should be on the graphics? I'm having trouble thinking of what they should be -- I think the images are purely decorative.

Based on reading a bit more on this [1] [2], I believe we should add a blank alt text tag alt="" to these decorative, ambiance graphics so that assistive tech like screen readers will know to ignore them (as they add audio clutter).

[1] Example 4 in this W3C article https://www.w3.org/WAI/tutorials/images/decorative/#image-used-for-ambiance-eye-candy
[2] Specifically example 9 in this Webaim accessible alt text article https://webaim.org/techniques/alttext/

MMiller_WMF added a comment.EditedMay 12 2020, 9:37 PM

@kostajh -- could you please respond to the previous couple comments, about the "publish" button and about alt text?

Regarding the links in final tip for each task type, I would like us to follow the same logic and links as we did with the task explanation widget from T235046: Newcomer tasks: task explanation widget. If a wiki has a link available for a given task type, then the line with the link in it should show up in the quick tip. If it does not have a link, it should not even have the line. For cells in the spreadsheet like F25 and F31, the link in the text should likewise only be made if the wiki has a link for that type of task. And although T235046 only shows our four target wikis, this would naturally apply to the other wikis that have newcomer tasks, and whichever links they have along with their task explanation widgets. How does this sound?

We may replace these later based on work from T211734: Newcomer tasks: develop standard help content to guide newcomers.

I'll put this in the task description.

MMiller_WMF updated the task description. (Show Details)May 12 2020, 9:38 PM
MMiller_WMF updated the task description. (Show Details)

the intention is not for it to be an actual button that publishes changes, or an actual button at all. It's really just meant to be a picture of a button, and the user is meant to see it and then find the real version in the editor, and then click that. But it sounds like this will probably be more trouble than it's worth. So let's do away with this supplement in the tip, and just have text. I went through and changed the relevant rows in the spreadsheet (rows 7, 13, 20, 26, and 32) to remove this button. I changed the text for desktop and mobile in those rows to explain it instead. How does this sound?

@MMiller_WMF that sounds fine, although if you want to settle for rough approximation of what the button should look like (rather than an exact copy of it) I think we could do that.

@RHo -- what do you think the alt-text should be on the graphics? I'm having trouble thinking of what they should be -- I think the images are purely decorative.

Based on reading a bit more on this [1] [2], I believe we should add a blank alt text tag alt="" to these decorative, ambiance graphics so that assistive tech like screen readers will know to ignore them (as they add audio clutter).

[1] Example 4 in this W3C article https://www.w3.org/WAI/tutorials/images/decorative/#image-used-for-ambiance-eye-candy
[2] Specifically example 9 in this Webaim accessible alt text article https://webaim.org/techniques/alttext/

OK that makes sense, I'll set blank alt text.

Regarding the links in final tip for each task type, I would like us to follow the same logic and links as we did with the task explanation widget from T235046: Newcomer tasks: task explanation widget. If a wiki has a link available for a given task type, then the line with the link in it should show up in the quick tip. If it does not have a link, it should not even have the line. For cells in the spreadsheet like F25 and F31, the link in the text should likewise only be made if the wiki has a link for that type of task. And although T235046 only shows our four target wikis, this would naturally apply to the other wikis that have newcomer tasks, and whichever links they have along with their task explanation widgets. How does this sound?

Sounds good!

Thanks, @kostajh -- I do not think we should include the button at all in that final tip, even a rough approximation. Let's just go with the text.

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

@kostajh -- I was looking around in TranslateWiki and I noticed that the QQQs don't match the columns in the spreadsheet. Was this deliberate?

For instance, the message screenshotted below has a QQQ of, "The main tip in tipset 1 of 6 explaining how to copyedit an article. This message is for the "help panel" feature. See this page for context and images." (with the link going to help panel info).

But the QQQ in row 8 of the spreadsheet is: "The first of a set of six tips explaining how to copyedit an article, as part of the "newcomer tasks" workflow. Prototype here: https://oacaib.axshare.com/#id=iqfam8&p=02_article-lamington"

Another example is the following, about one of the example sentences. Its tip (from row 5 in the spreadsheet) should read, "An example sentence included as part of an editing guide."

@kostajh -- I was looking around in TranslateWiki and I noticed that the QQQs don't match the columns in the spreadsheet. Was this deliberate?

Yes, the QQQs don't match because the actual implementation differs from the way it is laid out in the spreadsheet -- instead of a single tip message there are multiple i18n messages that comprise a "tip" (the stuff that goes in each tab in the guidance screen). We talked about this here T245786#6094707 and in some follow up comments, but this is the type of thing that (I'd like to think anyway), in a more normal work environment and schedule, I would follow-up on with you to clarify that it's OK. Beyond breaking up a single i18n message into multiple messages, I made some (what I thought were minor) changes:

  1. Shortened the text
  2. removed the use of double quotes because adding those in the qqq.json file is really annoying to look at (you can't just enter "something", the double quotes are always escaped so it looks like \"something\" and this gets really tedious quickly when trying to add dozens of messages.
  3. Removed the link to the prototype because (1) I'm not aware of other places where qqq messages directly link to an off-wiki source (maybe it's OK?) and (2) our standard practice has been to link to our documentation pages, where I also intended to follow-up by providing a link to the prototype and/or to live demo on beta wikis, but I forgot to do this. Should we do that?

Another example is the following, about one of the example sentences. Its tip (from row 5 in the spreadsheet) should read, "An example sentence included as part of an editing guide."

That seems like a mistake on my part, because following the format used in the other messages it should be something like The example sentence in tipset 1 of 6 explaining how to copyedit an article. The word "earth" should be deliberately misspelled in the local language -- we are demonstrating what a typo looks like. {{doc-growthexperiments-help-panel}}, e.g. it should reference the task type and also have the explanatory information from the spreadsheet. I can follow up on double-checking others.

@kostajh @Tgr @RHo and I talked about the QQQs today. We decided that:

  • Instead of linking to Invision mockups, we'll link to a mediawiki.org page containing static screenshots.
  • I will go through TranslateWiki and modify the QQQs.
kostajh reassigned this task from kostajh to MMiller_WMF.Jun 3 2020, 11:00 AM
kostajh moved this task from Code Review to In Progress on the Growth-Team (Current Sprint) board.

Coding wise, I think this task is complete so I'm marking in progress and assigning to @MMiller_WMF to finish modifying the QQQs, sounds OK?

While testing T244541: Newcomer tasks: suggested edit screen in guidance, I noticed two aspects of Quick tips that probably should be taken into consideration:

  • the text never refers to the fact that there is a maintenance template on a suggested article. However, the info about the template is important - after all, it's the reason why the article is in SE, and the template itself often has some additional info on what needs to be done.

Also, it might be not easy for a user to find the place/section in the article that needs attention - e.g. Španělština

  • the link to documentation is consistently on the last tip (6th or 7th). Is there any reason of not adding it to the first tip?

@kostajh -- I have now updated all the QQQs. They link to this new "guide for translators" page that I made: https://www.mediawiki.org/wiki/Growth/Personalized_first_day/Newcomer_tasks/Guidance_translation_guide

Should this go to QA?

@Etonkovidova -- thank you for those observations. We decided that explaining maintenance templates would distract newcomers from just starting to make the edit. And the reason we decided to put the documentation on the last tip is because we think that the tips explain the most important parts of the documentation. It's only once the newcomers gets through all the tips and is still confused that we think they should click the link and leave the page.

@kostajh -- I have now updated all the QQQs. They link to this new "guide for translators" page that I made: https://www.mediawiki.org/wiki/Growth/Personalized_first_day/Newcomer_tasks/Guidance_translation_guide

Should this go to QA?

I checked the page (just in case that "go to QA" was referring to the page) - looks fine.

@Etonkovidova -- thank you for those observations. We decided that explaining maintenance templates would distract newcomers from just starting to make the edit. And the reason we decided to put the documentation on the last tip is because we think that the tips explain the most important parts of the documentation. It's only once the newcomers gets through all the tips and is still confused that we think they should click the link and leave the page.

Thank you for the explanation - my reasoning was that not many users would click through all those tips, and, there is plenty of space on the first/second tip to add the documentation link. Also, the documentation has much more complete information about the editing action (supposedly).

Etonkovidova updated the task description. (Show Details)Jun 10 2020, 1:45 AM

For @RHo and @MMiller_WMF review - the text on desktop and mobile is according to the spreadsheet; no issues were found.

Two observations:
(1) In two places there "neutral tone" and "content should be neutral" is mentioned ("Copy edit" tip number 4; "Expand" tip number 3) - it might be useful for a user to have it as a link to the relevant page, e.g. on enwiki - https://en.wikipedia.org/wiki/Wikipedia:Neutral_point_of_view. This is an important concept which is not that intuitive.

(2) the tips for "Find references (sources for existing articles)" has pictures that are, in fact, not so obviously seen:


When a user follows the instructions in the next tip - "When you've found a source, click at the end of the sentence and then click the "Cite" button ." - the menu does not display the icons -there will be a link inspector with the default to "Automatic". The icons are not displayed

Only when a user switches to "Manual" , the icons will be present:

Otherwise there is no connection between icons in the tips and VE Cite tool.

Thanks @Etonkovidova - moving to PM review as I think your observation (1) makes sense but can be addressed separately as a new improvement to the guidence content and (2) is fine since the icons are more illustrative in that context.

For @RHo and @MMiller_WMF review - the text on desktop and mobile is according to the spreadsheet; no issues were found.

Two observations:
(1) In two places there "neutral tone" and "content should be neutral" is mentioned ("Copy edit" tip number 4; "Expand" tip number 3) - it might be useful for a user to have it as a link to the relevant page, e.g. on enwiki - https://en.wikipedia.org/wiki/Wikipedia:Neutral_point_of_view. This is an important concept which is not that intuitive.

  • Defer to @MMiller_WMF - I'm 50/50 on whether adding the link is too detailed for this "quick tip", even though I agree it is an important concept that is not so clear. If we did want create a new task to add in this link, may I suggest also reviewing whether it also makes sense to link out to pages to better explain references to reliable/verifiable and Encyclopedic content?

(2) the tips for "Find references (sources for existing articles)" has pictures that are, in fact, not so obviously seen:


When a user follows the instructions in the next tip - "When you've found a source, click at the end of the sentence and then click the "Cite" button ." - the menu does not display the icons -there will be a link inspector with the default to "Automatic". The icons are not displayed

I think this is OK because the icons in tip Add a reference tip #5 are used for illustrative purposes, not to indicate where to click. They will display a better with more spacing around them once T254527 is completed. Alternatively, @MMiller_WMF - we could also consider not using them at all if they are confusing and don't add that much more to the understanding of the task. We don't necessarily want the user to use the "Manual" step of adding a citation since the Automatic option should in theory be easier to use.