Designing "Tours" for MuseScore
Those of you who have installed any recent builds of MuseScore 3 have presumably seen the new Tours facility (if not, try Help / Revert to Factory Settings). These were implemented as part of GSoC 2018 by Joshua Bonn, with me as mentor.
The tours are something we are hoping to use effectively to teach newcomers about MuseScore. The idea is for help to pop up as needed - the first time you perform some specific action. That includes your first start of MuseScore, so you get an introduction to the program before trying to do anything else. But it also extends to things like, the first time you open a palette, etc.
There is a pretty good set of sample tours implemented already, but these are not set in stone; we have the ability to change any of this. Add new ones, rewrite some, delete some, etc. They are implemented as XML files in the GitHub source as https://github.com/musescore/MuseScore/tree/master/share/tours and hence can be edited by anyone, but I think it will be important to have some amount of consistency and attention to finding the right balance between having enough content and avoiding bombarding the user with so much information that he disables the tours before giving them a chance.
I would like to take charge of this for now to make sure we have the right set before release; hopefully also have some of the work in place before beta. Rather than encourage people to just go in and edit these themselves and possibly end up with a hodge-podge of tours that feel inconsistent and possibly overwhelming and yet incomplete at the same time, I want to start by having some discussion here to see what kind of consensus we can find on an overall approach. Then I will go in, make an initial pass to set things up, and we can go from there.
So, what ideas do you have for these tours? The easiest tours to add are ones that should be activated on the first use of a given action or widget - this can be set up with no code changes required at all. So, adding a tour that starts when you first open the Piano Roll, for instance, is easy. It's also possible with only a little code to make a tour that is "smarter", like one example I've always thought about, warning the user if he tries to add a slur between two notes of the same pitch that he probably meant to add a tie instead.
For more info on how the tours are created, see https://musescore.org/en/node/274365
Comments
Since the #1 FAQ has the answer "use voices" there should be a tour that pops up the first time the user inputs a note on top of another note. That is, they have a C entered, select the note in note input mode and press A. The tour could have a box that says something to the effect "Did you know you can enter multiple notes on the same beat using voices? Click this link (that leads to voices in the handbook) for more information."
If a tour cannot allow for this, I believe it is a shortcoming that should be overcome.
In reply to Since the #1 FAQ has the… by mike320
Great call! This falls into the same category as my slur/tie example - there would be no way to trigger this automatically without a code change, but the code change itself is trivial, just finding the right place to add two lines of code.
The trick is finding the right trigger - identifying user action exactly should active this. Your sugestion seems like a good start, although my guess is people probably try all sorts of other things, so we'd probably need to identify a few other possible triggers. And of course, it's totally legitimate to press "A" with a "C" selected if your goal is simply to replace the note. Maybe a little more specific would be, if they try to enter a new note of a different duration than the current one? Although to be sure, some uses of multiple voices at least start out with the same durations (eg, four quarters in top voice, two quarter followed by four eighths in bottom). In at least some of those cases, the user might have tried to manually flip them first, so that could be also something to look at.
Anyhow, yes, dealing with that would be AMAZING. And really, even if we have false positives - the tour is triggered unnecessarily - people still learn something good for next time.
I just wonder - if available - shortcuts should be mentioned, also in sense of accessibility. But could be also to overpowered ;-).
In reply to I just wonder - if available… by kuwitt
You mean, one page (let's call the contents of each specifically dialog that for now) of the startup tour mentioning that shortcuts are available in general and can be customized, or mention the specific shortcut in each tour that is triggered by a specific action? Both are good ideas :-)
In reply to You mean, one page (let's… by Marc Sabatella
I imagine a blind user or user with visual impairments listen to this tours via screen reader an hears for example (note input toolbar): "You can select a duration to add by clicking one of these icons." I'm not sure if this description is clear for such an user (or if there should be mentioned the corresponding shortcut).
In reply to I imagine a blind user or… by kuwitt
I think blind people are more inclined to read the documentation and take note of key presses that will enable them to do what they want. They don't get the immediate visual feedback that sighted people do. Since most blind users are drive-by's in the forums I don't know if we'll get good feedback concerning this.
In reply to I imagine a blind user or… by kuwitt
Ah, good point. The overall experience for blind users is not that great for MsueScore in general. I mean, we've done a lot, but a huge amount of things still can't be done without clicking, mostly anything beyond navigating an existing score or basic note input. So a good chunk of what's in thoseMuseScore anything much beyond use as a score reader (which is something, but still...). But we should plan for the future, and try to make the wording of the tours make sense to blind users where possible. Of course, another possibility is to simply design a different set of tours for blind users, which might actually make more sense. Anyhow, consider me very sympathetic to these concerns; as you may know, two of the previous GSoC projects I mentored were on accessibility.
In reply to Ah, good point. The overall… by Marc Sabatella
If you've paid attention to the forums, you know that assisting blind people is a priority to me. Anything that will make it easier for the blind is great, but I have my doubts that shortcut names in the tours would be useful. If tours give links that users can follow to the handbook, then we could work on improving the handbook to incorporate explanations of features that are intended to make MuseScore more handicap friendly rather than only a chapter, that BTW still needs to be there, that explains some of the accessibility features.
In reply to Ah, good point. The overall… by Marc Sabatella
Yes, I know ;-). But as mentioned somewhere on an other comment: Maybe it isn't the most important issue concerning the development of MuseScore, but it always has to be put to the test.
Here's a very specific question:
A tour can consist of a succession of separate messages, where hitting "Next" takes you through them in order. So the tour for some given feature could consist of one long message that tells you the whole story at once, or a succession of messages that tells it to you a bit at a time. The latter approach is the way to go for sure if each message needs to highlight a different UI element, which is a nice feature. But in the cases where we really don't need to do this, would people rather see one long explanation or see it broken into pieces with Next? Other than the part about highlighting different UI elements, what might the answer depend on? I could see if it's possible to tell "enough" of the story in the first message but then having additional messages to go into more detail, for instance.
In reply to Here's a very specific… by Marc Sabatella
I would say for consistency of design, the pop ups should have more shorter messages rather than one long message. I think more people will also read several shorter messages than one long message. Think about how many people ask questions because they never read the handbook. I don't think these people will want read a longer dialog box.
In reply to I would say for consistency… by mike320
Guess why my posts are usually very short ;-)
In reply to Guess why my posts are… by Jojo-Schmitz
Because your first language is German? ;-) I notice your German posts tend to be a bit longer than your English ones.
In reply to Because your first language… by mike320
German is a slightly wordier language ;-)
In reply to I would say for consistency… by mike320
Well, I tend not to read any sort of "next-next-next" guide in which it remains a mystery how long the guide is going to be. So there should at least be a progress indicator (e.g. screen 1/20 in this tour), and/or the option to click a button/link that will fold out the entire series in a single screen.
Imagine you're trying to read a single page or a single section in a user manual, but you're forced to read it through a slit in a cardboard.
In reply to Well, I tend not to read any… by ugcheleuce
I agree, that would be a nice enhancement.
I'm adding a tour upon dropping a volta explaining how to expand a volta using Shift+Right: https://musescore.org/en/node/280829
In reply to I'm adding a tour upon… by ericfontainejazz
Nice! FWIW, there are a small handful of more "general" tours I'd like to see added (e.g., ones for score comparison tool, mixer, and piano roll editor), but a larger number of really specific ones like this, triggere don a specific action that often either causes or results from confusion. Some of these I'll add myself as I find the time, but I'm more than happy for folks to jump in and tackle ones they are interested in.
Examples:
trigger a tour on use of voice 3 if voice 1 is empty: "are you trying to enter the tenor part in an SATB arrangement? if so, please use voice 1"
trigger on completing note input in last measure of score: "want more measures? here's how"
trigger on delete range selection: "want to delete the measures themselves? here's how"
trigger on adding a slur between two notes of same pitch: "did you mean tie?"
trigger on adding a note in voice 1 on a beat where there is already a note there: "maybe you want to switch to another voice?"
etc
In reply to Nice! FWIW, there are a… by Marc Sabatella
That first example "trigger a tour on use of voice 3 if voice 1 is empty..." I don't think that should trigger a tour in the way you suggest. The reason is it borderlines on clippy...who got a little annoying trying to guess what user was doing. Maybe user was indeed trying to add an secondary tenor voice in a SATB?
I'd rather a basic voice tour be triggered upon the moment of clicking voice buttons [1],[2],[3],[4] or Ctrl->Alt->1,2,3,4.
Additionally, I've always thought the [1],[2],[3],[4] buttons could be improved with some context. I realize they have a mouse hover tooltip, but just looking at the toolbar, basically every other button makes sense from it's icon. Except for those voice buttons. As they're just numbers without content, they could mean anything (beats?, staff numbers?, etc.). Maybe putting "voice: " label before the first voice button would go a long way into letting people know that they're voices. Maybe there is some more creative icon than just numbers.
But the rest of your potential tour examples sound good to me.
In reply to That first example "trigger… by ericfontainejazz
No doubt there some legitimate use case for adding voice 3 while voice 1 is completely empty - but probably 99.99% of such cases will be the (extremely common) user error I mentioned. I'll take annoying 0.01% of users exactly once (because the tour only shows once) if it means saving 99.99% from endless frustration over the undeletable rests that result from this error.
In reply to No doubt there some… by Marc Sabatella
Ok, I was not aware that the false-positive rate would be so low, but I believe your stats on that, in which case yeah it would make sense for a tour.
In reply to Ok, I was not aware that the… by ericfontainejazz
I don't think his numbers are scientific, but they make the point that a LOT of people make the mistake and ask how to fix it in the forums.
In reply to No doubt there some… by Marc Sabatella
Obviously my numbers are made up. But consider, needing voice 3 at all is pretty uncommon, and in most cases where you would be using it, you'd first enter notes into voice 1 and probably 2 as well. But sure, we wouldn't want the message to assume you are doing the wrong thing, just give a heads up.
If I can make a suggestion for improvements of the Tours feature, please make Tours discoverable outside of an action in the editor. E.g. instead of racking our brains for the best user action to trigger one or more pop-ups, give the user a full list of tours (e.g. a dialog box under Help > Tours > Show all Tours...)
i) which shows all the tours currently available
ii) which show as ticked/completed the ones they have seen already or chosen to skip.
iii) which users can trigger randomly if they are curious about a feature that they would never have stumbled on if one were to wait for the correct trigger.
iv) which users can individually re-trigger, should they want to revisit a Tour they have seen already or cancelled since they did not want to see a particular tour at the time. This would be much more granular than Reset tours and take some of the anxiety out of missing something covered in a tour (e.g. you know there is a way to get back to it).
For those with a gamified approach to learning / discovery of features, giving a single dialog box with All Tours and which ones they still have to go through, will be compelling enough to go through all of them. (I am of the type that wants the dashboard green / all the boxes ticked / strings translated)
A single dialog view of tours would also increase the notability of the tours during a release announcement, e.g. 3.0.0 had 10 tours, we added 10 more in 3.1.0 (and ideally all the new features that were added should have a tour). Without the single dialog, one would never be able to perform all the actions that trigger all the tours. The more obscure the subsystem/feature that the tour covers, the less likely it is that the casual/unfamiliar user will stumble on it by chance.
If the individual tours become so many that they could potentially overwhelm the user new, one could use the Basic / Advanced separation to shield entry-level users from more of the "obscure" features (similar to what is done with the palettes).
I strongly support mike320's statements on the thread w.r.t. having a link to the page in the handbook that covers a particular topic in detail. The learning / discovery should not end with the end of a Tour. If done right, the Tours can be the gateway to learning and features discovery.
In reply to Mark and Joshua - thank you… by Riaan van Niekerk
One additional thing I want to mention as a way to improve discovery for new features that user might not have triggered is to display untriggered tours on boot on splash-screen...I made this feature request in April 2016 (https://musescore.org/en/node/108606) but it turned into a debate about microsoft's clippy.
In reply to Mark and Joshua - thank you… by Riaan van Niekerk
Yes, having a "menu" (maybe not in the literal GUI sense, but maybe so) of tours is on the "to do" list (well, mentally, anyhow, I don't think there is an actual issue in the tracker for this). I imagine it being reachable from Help / Tours, and including checkboxes to indicate which tours have been seen and to allow you to toggle them yourself. This also supposes we have user-visible titles for the tours.
Links from the tour to appropriate context help would also be nice indeed. We have some of the mechanism in place already via the little-known F1 context help feature (hover over something in score, press F1...)