tchay wrote:

What sort of ideas are you thinking about?

I'm very open to suggestions. But there are a few things that could be easier:

1. People have to manually construct the guider ID.
2. You have to do multiple calls to initGuider.
3. Some things like the next button could potentially have less boilerplate.

One idea is to pass a name and array of steps to a wrapper method, with automatic features like a next button on every step but the last.

Note that the i18n change is already a small improvement on this front, in that you can just use somepropertymsg: 'message-name' for i18n.

swalling wrote:

Speaking as semi-technical end user, making users write JSON for this one purpose seems a bit crazy. The people who will conceivably write tours expect and understand writing JavaScript in the MediaWiki namespace as the standard for creating gadgets and other interfaces. Unless there's a really really good reason to deviate from this standard, I would rather not chance hurting community adoption.

One idea is to have two APIs:

1. One is a JavaScript API with the full flexibility of Guiders, with just some convenience wrapping (e.g. possibly automatic IDs and almost certainly easy i18n).
2. The other is more high-level, and would maybe even use a simple JSON structure instead of JavaScript as Terry suggested at https://bugzilla.wikimedia.org/show_bug.cgi?id=43531 (not set on this either way).

If you want, you can brainstorm ideas at https://www.mediawiki.org/wiki/Guided_tours

Steven, the set of people who write JavaScript on Wikipedia is not that big. So if we can provide an option that attracts people who write things like Wikipedia:Tutorial, that's a win.

Also, bear in mind that JSON is a focused subset of JavaScript, rather than something totally new like Lua.

Sorry, the brainstorming page is https://www.mediawiki.org/wiki/Guided_tours/API_brainstorming .

tchay wrote:

Right now they don't even write JSON, they write Javascript. JSON would be a huge step up!

I believe more ideal would be if a tour looked more similar to a (or a bunch of) mediawiki template call. Right now I don't think that's feasible in the short term because features like auto-advancing the guider haven't settled until we actually write more tours. But it's not unreasonable to expect we can reach that given that initiguiders inside the tour look very similar to a key-value list as it is.

I just thought it'd be nice to have a discussion along what lines we are thinking publicly in bugzilla. We definintely want to make writing guided tours more accessible both in terms of security (mediawiki namespace is necessary but too restrictive IMO, at least for content parts, probably the entire tour) and in terms of degree of difficulty (there are too many things that HAVE to be done. For instance the guider ID has to be consistently named for it to work and the next element has to be explicitly called, etc.).

swalling wrote:

Right now they don't even write JSON, they write Javascript. JSON would be a
huge step up!

I wouldn't be so sure. JSON looks simply to people who know JavaScript. It still looks like code to really non-technical people.

Even if I agreed, I'm not even sure that we want that many tours popping up over the place anyway. I am not really seeing a compelling need to lower the barrier to writing interactive interfaces that low. Modals are best used with care, since they interrupt users.

I think JSON is simpler than anything-goes JS, but it's clearly not trivial, and some people are not going to be able to do either.

I do think we want to make tours easy to write.

First, no one has to use a tour. You don't have to do the "how to read article history tour" to read article history. You do it if you want to, perhaps linked from Help:Page history. So we're not interrupting people who just clicked the history tab and want to get to the point.

Second, tours are easily dismissable, so if you do start on some tour, and realize, "I already know all this", you just click the x.

Basically, I don't see tours as a new interface. After all, the tour itself doesn't allow you to do anything; you still have to e.g. do the actual edit.

It's something optional that shows you how to use an existing interface.

swalling wrote:

It's something optional that shows you how to use an existing interface.

You cannot be too careful about educational tools like this. See also: Clippy. The line between a helpful popup and an annoyance which appears too often is finer than you might think.

Clippy was unpopular precisely because it showed by default (and in a very annoying way).

Tours would never show by default, only when you start one by putting tour= in your URL. In practice, that's almost always going to be when you follow a link from some help or project page.

We may want to show them by default in a few cases.

However, that doesn't mean we have to limit the library of tours that are just available to take (and can be linked from help pages).

Also, they can be started from a cookie, but ordinary Help: or Project: pages clearly can't do that.

I added a proposal to spur discussion at https://www.mediawiki.org/wiki/Guided_tours/API_brainstorming

This could help with things like an isTooltipOnly property, or other tour-level information.

I've started this, based on the defineTour idea. This will make it much more elegant to add isSinglePage and shouldTrack.

I've made an initial Gerrit (https://gerrit.wikimedia.org/r/#/c/47561/). It still needs tests, which I'm going to amend the commit to add.

Let me know what you think.

That commit got merged, so I'll do the tests in a separate one.

Tests are in https://gerrit.wikimedia.org/r/#/c/47698/ .

Merged.

I'm going to go ahead and mark this fixed. However, you can still use the brainstorming page (https://www.mediawiki.org/wiki/Guided_tours/API_brainstorming) and create bugs with proposals.