At https://en.wikipedia.org/w/index.php?title=Wikipedia:VisualEditor/Feedback&oldid=572181319#Inserting_reference there are comments that the instruction manual is too difficult to find, and requests that contextual help be added to the various dialogs.

These help links should obviously open in a new window/tab, and the target needs to be configurable on wiki as help pages are not static and get split/merged/reorganised over time.

turingt wrote:

Maybe, the way to make the target page configurable can be creating a fixed redirect page for each link, so that we can change the redirect target.

As a start, maybe add the (?) icon next to each of the page settings controls so we can give some blurb for users? I'm happy to write the copy on the commits. :-)

Change 142468 had a related patch set uploaded by Alex Monk:
Allow FieldLayouts to have help text

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

Change 142468 merged by jenkins-bot:
Allow FieldLayouts to have help text

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

So I suppose now the job is to start writing copy…

So for adding these to the page settings controls, it should now just be a case of adding the new messages and using them as the config.help for each setting's FieldLayout. James, are you planning to do this?

It looks like some work was done in Gerrit change 147751 and then reverted

Change 159095 had a related patch set uploaded by Alex Monk:
Make help button for FieldLayout frameless again

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

Change 159095 merged by jenkins-bot:
Make help button for FieldLayout frameless again

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

Change 159104 had a related patch set uploaded by Alex Monk:
Provide contextual help for the page settings dialog's controls

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

First one done. We'll seek feedback on this approach and then roll out for the rest of the dialogs.

Change 159104 merged by jenkins-bot:
Provide contextual help for the page settings dialog's controls

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

Change 160371 had a related patch set uploaded by Jforrester:
Add contextual help to all remaining meta dialog controls

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

Change 160371 merged by jenkins-bot:
Add contextual help to all remaining meta dialog controls

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

The page settings ("meta") dialog now has a complete set of contextual help. Will wait for further user feedback before doing the rest of the dialogs.

Did we get any feedback?

Change 186108 had a related patch set uploaded (by Jforrester):
MWMediaDialog: Add contextual help for controls

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

Patch-For-Review

Change 186108 merged by jenkins-bot:
MWMediaDialog: Add contextual help for controls

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

Those who noticed the contextual help on the meta (page settings) menu - I'm not one of them - apparently didn't think it was worth commenting at WP:VE/F, or its equivalent at mediawiki.org. That may because contextual help was added to the VE menu least used. Or because no one was overwhelmed by the wording in the contextual help popups. Or because there was no obvious way to suggest improvements in wording. Regardless of the reasons, the lack of a response should absolutely not be taken to be a polling of the user community.

More generally:

• Contextual help absolutely is needed. The lack of this is one of the major weaknesses of wikitext editing. I don't think user feedback is needed to confirm this need. But if there is any doubt, then I suggest posting this the question ("Should VE menu items have contextual help?) at one or both Feedback pages.
• The content of contextual help should be similar to templates: visible to everyone, each on separate page, with a related talk pages, but not necessarily editable by anyone but an admin. What isn't needed is some programmer-added contextual help; what is needed is a system so that creating and modifying contextual help is done by members of Wikipedia communities. [For example, pages could be named something like this: Help:VisualEditor/ContextHelp/label, where "label" is a unique name for where the contextual help will appear.
• Contextual help should be able to include links - because linking to the relevant section (or anchor point - see WP:EIW, for example) is important when the (relatively short) contextual help isn't sufficient.

In T53798#1029938, @John_Broughton wrote:

• The content of contextual help should be similar to templates: visible to everyone, each on separate page, with a related talk pages, but not necessarily editable by anyone but an admin. What isn't needed is some programmer-added contextual help; what is needed is a system so that creating and modifying contextual help is done by members of Wikipedia communities. [For example, pages could be named something like this: Help:VisualEditor/ContextHelp/label, where "label" is a unique name for where the contextual help will appear.

MediaWiki already solved this problem long ago with the i18n system and the MediaWiki: system namespace. Either look at the changes made to the i18n/en.json file, or search for the text you want changed, to find out which page in the MediaWiki namespace an admin needs to change. These MediaWiki pages can also have related talk pages.

In T53798#1029938, @John_Broughton wrote:

• Contextual help should be able to include links - because linking to the relevant section (or anchor point - see WP:EIW, for example) is important when the (relatively short) contextual help isn't sufficient.

I think we could allow that, but we'd need to change OO.ui.FieldLayout to accept HTML for the 'help' configuration, and then make VE-MW parse the help messages.

The relevant documentation about messages (i18n system) appears to include

• https://www.mediawiki.org/wiki/Help:System_message
• https://www.mediawiki.org/wiki/Localisation#Adding_new_messages
• https://www.mediawiki.org/wiki/Localisation_file_format
• https://www.mediawiki.org/wiki/Help:System_message#Finding_messages_and_documentation

The last of these says "How each message is used by MediaWiki, variables available, parameters used, limitations, et cetera is explained with the complete documentation in the qqq pseudo-language files", with a link to here:

• https://translatewiki.net/w/i.php?title=Special%3ATranslate&task=reviewall&group=core&language=qqq&limit=5000&tux=0

On that page, if I change the Group field to any of the four VisualEditor groups, and then look for the messages that James added to all items related to one VE menu, I can't find those messages. Should I be looking somewhere else, or are the messages not in the i18n system?

They are definitely in the i18n system, for example https://meta.wikimedia.org/wiki/MediaWiki:Visualeditor-dialog-meta-categories-defaultsort-help/en

We disagree with the premise; instead, there should only be help links where they are useful to explain the complexity of a control to the user. Most of this is already done, and the focus areas for this release don't have this level of complexity required. Consequently, we decided to remove this from the Q3 blockers list at the triage meeting on 2015-02-11.