Add contextual help
Closed, ResolvedPublic3 Story Points

Description

Each form field needs to have a help text that explains the search option behind it.
See comments below for help texts and help icon / positioning.

Restricted Application added a project: TCB-Team. · View Herald TranscriptJun 20 2017, 2:38 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript

…would be triggered by this (i)

@Jan_Dittrich : Could you provide us with texts for each option? We could come up with texts ourselves and edit them later but as the translators are really quick, we would make double work for the translators. If it's not possible, please give us some rough guidelines as to what should be in them (more explanation, mention the syntax, give warnings about limiting the search too much, etc).

One notice in the help for "This word" and "Exactly this text": "This word" does wiki-language dependent stemming, i.e. Searching for "Car" also finds "Cars". Wehn putting text in quotes no stemming is done. Don't know if such a complex topic is right for the help text, but wanted to point that out

Lea_WMDE changed the task status from Open to Stalled.
Lea_WMDE added a subscriber: Lea_WMDE.

waiting for the help texts

Pablo-WMDE set the point value for this task to 3.Jul 26 2017, 11:26 AM

Here is our current suggestion for the help text. Let us know what you think/what should be changed.

Link to doc with nicer formatting. Besides formatting, same as below.

These words:
Description: searches for these words in the title or text.
Be aware of the following:
multiple words can be entered here.
punctuation marks and other non-alphanumeric characters (with exception of the colon and comma) will be ignored.
there may be results that do not contain one or more of your search terms.
word stemming is applied. Example: If car is entered, the search will also consider cars. The word stemming is language specific.
Help page:
Syntax-Equivalent in the normal search: sesame street car

Exactly this text:
Description: searches for a specific sequence of characters. Punctuation marks are ignored.
Be aware of the following:
search is NOT case sensitive
punctuation marks and other non-alphanumeric characters (with exception of the colon and comma) will be ignored.
word stemming does not work here (but currently is?)
Help page:
Syntax-Equivalent in the normal search: Words in “ “, for example “Begin at the beginning”

Not these words:
Description: excludes pages containing these words from the search.
Be aware of the following:
Help page:
Syntax-Equivalent in the normal search: Words with - before them, for example -elephant

One of these words:
Description: at least one of the search terms has to be included in the page.
Be aware of the following:
Help page:
Syntax-Equivalent in the normal search: Words with OR in between then like Laptop OR Notebook

Structure
Page title starts with:
Description: searches for pages with titles that start with this word
Be aware of the following:
The search includes redirects
Word stemming is applied. Example: If car is entered, the search will also consider cars. The word stemming is language specific.
Help page:
Syntax-Equivalent in the normal search: words with intitle: before them like intitle:queen

Pages with this template
Description: searches for pages that contain exactly this template.
Be aware of the following:
you can only search for one template at a time
Help page:
Syntax-Equivalent in the normal search: words in quotation marks with hastemplate: before them like hastemplate:"missing information"

Source code contains:
Description: only looks for the search term in the source code.
Be aware of the following:
unlike other search fields, non-alphanumeric characters like ` and [ will be considered in the search.
will use word stemming and not look for the exact search terms. Example: If car is entered, the search will also consider cars.
Help page:
Syntax-Equivalent in the normal search: words with insource: before them like insource:thumb

Pages In language
Description: will only search in the language you choose.
Be aware of the following:
you can only search for pages in one language
Help page:
Syntax-Equivalent in the normal search: inlanguage: followed by a language code like inlanguage: es

Files and Images
File type:
Description: searches only for files of the selected type
Be aware of the following:
you can only search for one file type
you can only select the given file types from the drop-down menu
Help page:
Syntax-Equivalent in the normal search: words with filetype: before them like filetype:ogg

Width and Height:
Description: These fields allow you to specify the size of the file.
Be aware of the following:
this is only applicable to file types that have width and height, like videos and images.
Help page:
Syntax-Equivalent in the normal search: numbers with filew or fileh before them like filew:>800 fileh:>600

Doc can only be accessed by people who have some login.

Lea_WMDE changed the task status from Stalled to Open.Aug 16 2017, 9:51 AM
Lea_WMDE updated the task description. (Show Details)

Is there such a help thinghy already in the application that we can use?

@JeroenDeDauw Yes. We're wrapping each search element in a FieldLayout OOUI element (except for the file size elements which use a subclass of FieldLayout. The class has a help property that can be used.

Should be mostly done by https://gerrit.wikimedia.org/r/#/c/375946/

I did not find a description for the "Page title contains" field in the document. Likewise I did not find anything for the "File width in pixels" and "File height in pixels" ones. And for all fields I am not sure I picked the right text at all. I chose what is behind "Description:" in the document but for all I know this is the description we provided to UX. Anyway, we can easily add or tweak messages later.

should be mostly done by https://gerrit.wikimedia.org/r/#/c/375946/

Great! @gabriel-wmde or @JeroenDeDauw – should we have a look at the results together?

Feel free to comment on Gerrit. I'm also happy to talk but am only in the office during the morning this week. (Thursday till 10:00 and Friday till 12:00)

Deployed to the test wiki. I'm working on the missing help intitle and I think the help texts are too short and should contain the whole description.

Change 377732 had a related patch set uploaded (by Gabriel Birke; owner: Gabriel Birke):
[mediawiki/extensions/AdvancedSearch@master] Add help for intitle field

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

gabriel-wmde moved this task from Test to Review on the WMDE-Fundraising-Sprint-10 board.

Change 377732 merged by jenkins-bot:
[mediawiki/extensions/AdvancedSearch@master] Add help for intitle field

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

gabriel-wmde removed gabriel-wmde as the assignee of this task.Sep 13 2017, 5:31 PM

Since you can't have wikitext in messages (at least not for javascript), this will be complicated. Next step is writing to i18n@wikimedia.org and asking how I can implement complex messages in JS, if those messages should be split up (and reassembled with HTML) in the init script or if there is a bug in the JS version of mw.message( 'keyname).parse()

gabriel-wmde moved this task from Review to Doing on the WMDE-Fundraising-Sprint-11 board.

@Charlie_WMDE @Jan_Dittrich Please advise me on the markup for the formatting. Naturally, I'd go with a definition list, but that leads to line breaks that might not be wanted.

We could a) create special styles for the tooltips that remove line breaks and indentations. b) use simpler, less semantic markup.
I don't know what markup is best for accessibility, so you might also consider/research that.

Change 377993 had a related patch set uploaded (by Gabriel Birke; owner: Gabriel Birke):
[mediawiki/extensions/AdvancedSearch@master] WIP Add HTML contextual help tooltips

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

gabriel-wmde removed gabriel-wmde as the assignee of this task.Sep 14 2017, 9:57 AM

@Charlie_WMDE @Jan_Dittrich Please advise me on the markup for the formatting. Naturally, I'd go with a definition list, but that leads to line breaks that might not be wanted.

I'm fine with the line breaks as seen in your screenshot. What would be the alternative to a dl?

I think the way you made it is good.

We could a) create special styles for the tooltips that remove line breaks and indentations.

what tooltips?

b) use simpler, less semantic markup.

what would this mean for the user?

I don't know what markup is best for accessibility, so you might also consider/research that.

Afaik semantic markup is better for screenreaders. I don't know how much less we're talking about here though.

I'm sorry, I feel like all my comments are super unhelpful :/

What would be the alternative to a dl?

<strong> and <br> tags 😦 . So if you're fine with how it looks in the screenshot, I'll just continue, we deploy and can iterate after.

What would be the alternative to a dl?

<strong> and <br> tags 😦 . So if you're fine with how it looks in the screenshot, I'll just continue, we deploy and can iterate after.

I am :)

@gabriel-wmde can we put the name of the field into the help thingie as well? So in the case of your screenshot it would say on top

Exactly this text in a 1p larger text size and bold and gray. Like the headings in the drop down of the file type selector.

Yes, that's possible. I've created a patch that you can view on a developer's machine to get a visual impression.

Change 377993 merged by jenkins-bot:
[mediawiki/extensions/AdvancedSearch@master] Add HTML contextual help tooltips

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

Change 378230 had a related patch set uploaded (by Kai Nissen (WMDE); owner: Kai Nissen (WMDE)):
[mediawiki/extensions/AdvancedSearch@master] Fix coding style issue

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

Change 378230 merged by jenkins-bot:
[mediawiki/extensions/AdvancedSearch@master] Fix coding style issue

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

Deployed to http://tools.wmflabs.org/wmde-uca-test/core/

Some German translations probably need to be adapted for clarity.

Deployed to http://tools.wmflabs.org/wmde-uca-test/core/

Some German translations probably need to be adapted for clarity.

Is this our translation or have the texts been run through translate-wiki already?

Also two little things i noticed: when clicking on the "i" symbol to open the help text, and then clicking it again to close it, it stays highlighted until the focus is set to another place.
The other is the alignment of the field names and the "i"-symbols. In the mock they are on one line which is the line running through the middle of a search field like so:

whereas in the prototype they're all kinda lifted off to the top.

The German translations came from translatewiki.

Both things you describe are defaults given by the OOJS UI framework. If you really want us to deviate from the defaults, please open a new issue, copying the request for changes from your comment.

Both things you describe are defaults given by the OOJS UI framework. If you really want us to deviate from the defaults, please open a new issue, copying the request for changes from your comment.

I see. If that's the OOUI standard then we should keep it the way it is. Thanks!

kai.nissen closed this task as Resolved.Thu, Nov 2, 1:37 PM
kai.nissen claimed this task.