Topic on Talk:In-context help and onboarding/Flow

I suggest drawing a fairly sharp distinction between "in-context help" and "onboarding". The vast majority of users would benefit from in-context help, if that answers either "What does this specific feature [of VE, primarily] do?" or "How do I do this [in VE, primarily]?" By contrast, onboarding is (by definition) for new(er) editors, and its focus is on different things: "How can we help you do something useful, rather than futile?", "Here is a policy or guidelines that you don't seem to be aware of?", and similar.

For in-context help:

(a) Some time ago I suggested adding clear, helpful information to all of the editing options in VisualEditor. That followed a limited attempt to do so by the WMF developers - see, for example, in the page options menu, when "Options" is selected, the small "i" with a circle around it, on the right side of the dialog box. The critical parts of implementing such a system, I believe, are (a) adding "hooks" in all the right places (the small "information" icons), (b) enabling administrators of local wikis to add and edit the displayed text [raising translation/maintenance of "core" message issues, but I digress], and (c) enabling those administrators to add links within the text, so those more inclined could go to help and/or guideline pages.

(b) For "How do I do this", it could be very helpful if the Help icon in VisualEditor allowed an editor to select from (say) 50 to 100 different choices ("How do I add a footnote?"; "How do I cite the same source in more than one place in an article?"; "How do I add a category to an article") and, then, in the best of all possible worlds, see a brief screencast showing exactly how to do that thing.

There is, unfortunately, a larger issue. I'm sure that WMF sees the challenge as designing tools for in-context help and for onboarding, and then letting the community use these. Unfortunately, the English community (among the most active) has demonstrated, convincingly (in my opinion), that it's incapable of maintaining help pages - "maintaining" in the sense of "keeping current with the software changes that developers implement". For example, I'd give good odds [without having looked] that the vast majority of help and info pages for editing don't give at least equal weight to VisualEditor compared to the classic wikitext editor - yet WMF is in the process of introducing yet another type of editing software.

There is a solution to this problem, which I mention for the sake of completeness: WMF should take responsibility for core documentation, including in-context help, and including translation, for user interfaces. In other words, where WMF provides cross-wiki functionality, it should provide cross-wiki documentation. (Policies, guidelines, and processes that are wiki-specific would remain fully the responsibility of the local wiki to maintain.) Assuming that additional responsibility would cost WMF on the order of several million dollars a year [more to start, less ongoing], money that WMF clearly has. That wouldn't eliminate the role of the community in improving in-context help and other documentation management by the WMF; the community would have a supplemental role (as in, for example, "feel free to edit this to improve it").

Hello John

Concerning communities that take care of documentation, French Wikipedia has made a strong effort to have help pages for both wikitext and visual editing. See to insert a citation, with wikitext (the simple version, there are actually 2 other pages with an increasing difficulty!) and VE (one page, and that's all).

That community effort concerning documentation hasn't been made in a couple of days, but, with strong recommendations on how to write an help page and a blank check from the rest of the community, a dedicated wikiproject has been working on it since two to three years. That allows us to point newbies to an help page explained by the editor they use (in most cases VE). My point is that it is possible to maintain such pages and I don't think it depends of the size of the wiki.

Concerning documentation, edited and maintained by the WMF and translated by volunteers pages exist: Visual editing, Notifications types, Recent Changes, etc.

Hope this helps.

Trizek - I would never contend that it's impossible for a local community to successfully maintain a wide range of documentation to help with editing. I simply believe that it's very unlikely. If you could point to dozens and dozens of examples where communities do in fact devote plentiful resources to this, I'd be happy to change my conclusion.

And I'm aware of the VisualEditor user guide, since I helped improve large portions of that. But WMF has made no commitment to maintaining core user documentation, part of which would be to define what "core" is, and part of which would be to have a specialized group responsible for that - including, for example, the paying of translators.

That's your opinion. With one example, I see things as possible. If you need "dozens and dozens" of examples I'm afraid I can't do anything to convince you. :) My point is also that a situation can be different because of a given cultural apprehension of change, or how a community decides on everything. There is no miracle, just motivation.

Same thing concerning documentation and translation: motivation is everything. I believe more in a taskforce of specialized volunteers, recognized for their skills, than a group of paid editors.

Hi @John Broughton. I think you've raised a really important issue. Our notion of how to do this is that we will model the Help lessons, formats and styles our research proves are most effective. After that, we will need extensive community support to make sure the new help "lessons" reflect local policies and tech, which varies wiki to wiki considerably. So, on day 1, the new system will be an up-to-date and improved help facility. But how long will that last? Will the community continue to keep the modules up to date?

This problem is perhaps worse for the system we have in mind, since most of it will only ever be seen by newbies. After all, if you happen to see a Help page that is out of date, you have the ability to fix it—or at least report it as needing to be fixed. But you will probably never see any of these modules; the only people who will are the ones who have no idea how to remedy any problems they encounter.

I should note that we're not, for the most part, planning to focus this system on a whole lot of individual tools, as you suggest. At least for the first release. A large part of the impetus for this came from the New Editor Experiences research. In particular, this system addresses finding #8, which showed that "new editors’ greatest challenges are not technical but conceptual," in that they don’t understand wiki policies, including the “pillars” of Wikipedia like notability, neutrality and verifiability. Such policies, of course, change more slowly than tooling does. Still....

I wonder if we might address the problem of getting out of date by including a "Was this helpful" link with the modules? A user who clicks it would get a form inviting them to describe their problem. I don't know who would get the output of that form, but presumably there would be a page and maybe a group interested in helping newbies?

I think that John has a good point, and it's something that we should consider in the project design. It will be important to figure out who's responsible for updating the help messages long-term. If there's a situation where a change would need to be made in software rather than messages -- a different trigger, pointing to a different spot on the page -- then there needs to be an ongoing commitment from a product team to keep those updated. If it's just updating the words, then editors can do that -- but we'll want to talk to the community on the wikis that are using the feature, to make sure that there's a group of people who are willing to monitor and update in the future.

Regarding finding #8, that the greatest challenges are conceptual, that's why I mentioned "(c) enabling those administrators to add links within the [help] text, so those more inclined could go to help and/or guideline pages." For example, when adding a citation, the help/information pop-up could include [for the en.wikipedia.org system] the text "Be sure that the citation you're adding is from a reliable source", with "reliable source" being a link to https://en.wikipedia.org/wiki/Wikipedia:Identifying_reliable_sources . That guideline page is well-maintained by the English Wikipedia community, so there isn't a lot of reason to worry about that, and it has links to relevant Wikipedia policies, so it's a good place to start for those who want to understand conceptual issues.

Have best practices based on design research and usability will be in any case vital.

Based on my experience, there is a lot of pages that are considered as "good" while they are not easy to read or understand for newcomers.