ReaLearn desparately needs better tutorials

[mangowannamango]

I've copy-pasted my comment on this video:
https://www.youtube.com/watch?v=dUPyqYaIkYA

(with some edits):

I really appreciate the in-depth guide, but I wish each chapter had a demonstration AND a short tutorial. For instance, the main thing I want out of ReaLearn right now is to switch FX presets like you do at 11:40 in the video, but all you did was demonstrate the end result, not the process. I can't figure out how to set this feature up. I've been going through your GitHub user guide for days, and I haven't figured it out yet. I'm sure I will, but I wish it was a bit easier.

Your video presence is intelligible, but like I said, you skip over important details.
However, your writing style is, I'm sorry, but about 50% of it makes no sense to me or my friends who are also trying to figure out ReaLearn. Some specific examples, straight from your user guide (these are rhetorical, to show my point. You don't have to address them specifically):

"Don’t use this, this feature is not ready yet!" Then why mention it, or even include it in the app?
"This is really much easier to achieve using conditional activation, think about it." I've thought about it, and I don't get it. An explanation would have been better.
"Put your controller’s buttons into momentary mode, not toggle mode." At the hardware level? or in ReaLearn?
"You strictly need to use conditional activation if you …​
…​ want to activate/deactivate mappings using REAPER automation envelopes.
…​ want to sync the active/inactive state of a mapping with a dynamic track selector expression.
…​ want to activate/deactivate mappings in another ReaLearn instance.
…​ want to activate/deactivate mappings in another compartment within the same ReaLearn instance."
Those aren't use cases that a beginner (like myself) would understand. You referenced unfamiliar things as use cases for another unfamiliar thing. In order for this type of explanation to work, it needs to refer to familiar knowledge.

You've discussed in other comments sections not having enough time to provide certain tutorials. That is completely understandable. Is there any way we can support you to get some help refurbishing your user guide, making a new tutorial series, or getting someone else to edit and maintain your user guide? I would happily donate if I knew the money was going toward making it a more pleasant experience to learn how to use ReaLearn. Sorry if that seems a bit stingy, but even the greatest tool isn't worth my time or money if I can't figure out how it works.
I know it would grow your userbase because I have several friends who are ReaLearn-haters, and it's almost entirely because your guides are so confusing, not because ReaLearn itself is bad or anything. It's great.

I intend for these comments to be nothing but constructive because I REALLY want people to know how awesome ReaLearn really is. I just think it needs to be much more welcoming and approachable. And in my opinion, other than keeping the user guide up to date, I think the 2 best ways of doing that are:

1. Doing more "use-case"-format walkthroughs, where it's like, "Do you want to know how to do __? insert demo here (you have great demos already), and THEN MOST IMPORTANTLY: Give us a step-by-step on how you did that! Or if you're really short on time...maybe you could upload the relevant main compartments on GitHub, somewhere easily accessible, so we can at least deconstruct what you've done and tailor it to our needs. I am a GitHub NEWB! I barely even know how to download things from it! Over my head! Not ready to hop on that whole train!

2. Get someone else to do tutorials for you. Kenny style. Thorough, beginner-friendly, bite-sized. Properly titled for relevant use-cases/features. All in a playlist, and ideally referenced in the relevant categories of your user guide. Again, I would pay for this to happen.

Benjamin, I can't even imagine how hard you're working to make this happen. I want ReaLearn to thrive for many years. It's one of the coolest things I've ever seen. Seriously. And I truly think that if you dedicate some time to making what you already have more approachable and friendly to use, that THAT will do a better job of guaranteeing its survival than any amount of brand new features. Improving user support will be one of the best ways to grow the knowledge base, attract more people, help you feel like you have more of a community around it, and keep us from giving ourselves headaches by bashing our heads into the same issues that you could probably solve in seconds. I see how thorough you are with answering people's specific questions in the (now semi-obsolete) Reaper Forum thread. If you devoted half of that energy into improving your guides, we might not need to ask half the questions in the first place.

tldr; Your user guide is too long and wordy, and is not beginner-friendly, even though it could be.
I suspect you willl agree with the following sentiment, but I'll say it anyways: A thing doesn't need to be complicated in order to be powerful.

If my fixation on your clarity of communication is any indication, I am a music teacher. I spend a lot of time thinking about this, lol. If I ever end up teaching a music technology class, imagine how cool it'd be to get a tool like this in the hands of curious students. They could make templates for dayzz.

[mangowannamango]

Here's a reference video for the type of tutorial I would like (and, as it is a GitHub tutorial, it just so happens to be ancillary to being able to more appropriately use GitHub to request features from you):

https://www.youtube.com/watch?v=tRZGeaHPoaw

Notice how he often says something like, "Let's say you want to do ___." Then he _immediately shows you exactly how to do it, with reminders on the things he already taught you.

[helgoboss]

Thanks for your feedback!

Concerning the video

I'm not sure if you know about the "ReaLearn Tutorials" video series. It's linked on the official website under "Videos" and "Documentation". Apart from the fact that it deserves many more episodes, I think it pretty much fits your requirements. (What you watched is just the initial introduction video, which demonstrates a few things you can do without showing how).

Concerning the user guide

I agree with most of the things you say. There's definitely a lot of room for improvement.

One of the urgent issues with the user guide right now is that it's not up-to-date. It documents 2.16.0-pre.1 (one year ago). That's also why you won't find anything about "Units" in there. This situation is an exception. In the past, I never published a stable release without an up-to-date user guide. But release 2.16.0 was different. The plug-in was renamed to "Helgobox" and was mainly about Playtime 2, not too much about ReaLearn. Playtime 2 desperately needed to see the light of the world, so I published Helgobox 2.16.0 without including an up-to-date user guide.

My idea of the future documentation

The thing that I currently call "User Guide"is in reality a mix of:

• 70% "Technical reference" (most of the "Reference" section): Quite technical. Not beginner-friendly. Good for looking up some intricate details, but not good for gaining know-how.
• 20% "How-to" (some of the introductory sections and the tutorial section): Step-by-step introductions based on actual usage scenarios
• 10% "Developer info" (spread out over the whole document): Some "insider" info that should only be interesting to other developers.

In my opinion, this should be turned into multiple documents:

1. Tutorials (or "User guide"): This document should be approachable for the average user and explain things step by step, similar as you describe it. It should cover much more usage scenarios than the ones in the above 20%.
2. Technical reference: That would basically contain the 70% from above. It's probably best if I write this myself because I know best about all the intricate details. It can get quite technical - which is necessary because ReaLearn is also a sort of programming environment. The majority of average users might not even have to touch that reference. It's more something for people who want to get deep.

The separation into 2 documents has advantages:

• The user doesn't get overwhelmed by the technical reference (and therefore doesn't lose courage and doesn't become a "ReaLearn hater" ... LOL, didn't know they exist)
• Makes team work very easy (see below!)

What I can contribute in the near future

Not much ;) I hope to soon update the ReaLearn user guide, so that it at least reflects the latest changes.

Apart from that, I'm afraid Playtime 2 still has my top priority. Playtime has the potential to generate income, ReaLearn doesn't. I need that income to be able to work full-time on both products. That's why I can't focus on improving the ReaLearn user guide / tutorial situation in the short-term.

My suggestion

You seem to be quite motivated when it comes to ReaLearn! You are a teacher and look at this thing from a user perspective. How about you take matters into your own hands? ReaLearn is open-source, so contribution by others is welcome!

Contributing to the user guide in its current form is tricky. It's not up-to-date yet, so I would need to update major parts of it. Multiple persons would have to work on one document (which is tricky if you don't know Git and can get tricky even if you know it, depending on the amount of structural changes). In fact, there was a user guide contribution attempt in the past, but it didn't go very well. Because there was not enough communication about the planned changes in advance, and because I never found the time to cherry-pick and integrate this big amount of changes.

But if we divide the user guide into 2 documents as outlined above, it would work. I could concentrate on the "technical reference" and everyone (you, me, potentially others) could write "tutorials" as we please.

The form of those tutorials could be quite free and also the way the tutorials are submitted. There shouldn't be a high technological burden. Of course, even videos could be contributed.

When there are detail questions from people who want to make a tutorial, I would of course love to answer them.

How does that sound?

[mangowannamango]

Thanks for the in-depth reply.
"Motivated" is one word--certainly part of the equation. "Persistent to a fault" is perhaps more accurate. Those "ReaLearn haters" I mentioned gave up waaaay before I did. I should also mention, I was really frustrated those few days I was writing comments. Not just at ReaLearn, but with other life stuff. Sorry if it bled into my tone a bit.

The other motivations are:

1. I'm getting over a multi-year writer's block and I had a lot of free time this summer to deep rive into Reaper.
2. I have a live gig on bass guitar coming up, and I really want to use an octave pedal and switch over to a delay pedal at certain points. I was about to buy some, but they're expensive. I remembered that I bought the VST Guitar Rig a few years back (which already has what I need), and the only thing holding me back from going fully virtual was an aversion to clicking around with my mouse onstage (naturally). Enter ReaLearn, and now I can use snapshots to switch "pedals" with one press on my Akai or a MIDI foot pedal. (One of the "ReaLearn-haters" said this is possible without ReaLearn, but i hadn't heard of it, and I doubt it's as nice to use.)

Your Tutorial Videos:
Yea, I've seen them all. I should revisit the later ones because it's been a bit longer since I watched them. I did prefer those for my purposes. Not bad at all.
And yes, I was mostly referring to your long video. I understand it was intended as more of a demo and less of a tutorial, but in my opinion you already did like 70% of the work to make it both. And for something like demos and tutorials, I usually prefer all-in-one solutions (to cater to a varied audience). In any case, my biggest gripe is that, although most of my ReaLearn questions have already been answered somewhere by you, that "somewhere" is not usually intuitive to find. For instance, I finally found out that what I was looking for was "FX: Save snapshot". It was listed in the mapping panel the whole time, but I hadn't made it that far in the user guide since it's so far down the document. I think I found the solution on my own, after trying "browse FX", and when that didnt work, i tried saving unit-to-FX presets, hoping that it would perform the snapshot effect. And more, until I found snapshots. It's ok that you decided to save the more thorough explanation for the tutorials; it would've made for an even longer main video otherwise. My point is, it would've taken you about 20 extra seconds to add a subtitle or 5 extra seconds to mention in the video which ReaLearn target you were using to achieve that. I just couldn't find my solution since I didn't know what to look for. The teaching was split-up from the demonstration, making both of them less effective.

The User Guide being out of date:
Heard. You'll notice by our other conversations I haven't looked into Playtime yet. Seems cool. Will definitely be on my radar. And you're a human being. You're not Hermione Grainger with her time turner. I get it.

Future Documentation and what's next:
I like the sound of this, a lot. Perhaps to save on time, you could do a quick branch-off, preserving the vast majority of the current "user guide", renaming it to "technical reference" like you said, and then cut-pasting the current "quick-start" portion into a new userguide/tutorial doc? Or something to that effect, clearly noting that it is under construction? That way, we can get the ball rolling instantly, before you tackle all those "structural changes" right away. I can get to work on tutorials. And, this might go without saying, but I was hesitant to suggest I help out with tutorials because:

1. I didn't want to imply I could do it better than you. I think you taught quite well in your tutorials. It's just, you said yourself it hasn't been your top priority, and of course, there do need to be lots more of them made, by someone, if not you. I guess I am one of those "someones" I asked you to find.
2. I don't know if I understood ReaLearn well enough yet, but that's partially my perfectionism striving to understand it in its entirety before feeling comfortable with teaching it ( which is an absolutely faulty way to think). With that said, though, I can only teach what I know.

Also, since I wrote that first big comment, I have begun my journey into learning Git and GitHub. Daunting, but I have successfully uploaded my first repository. Still gonna be a while til I feel ready to actually contribute to code on anyone's projects, but it's a start. I will look further into how I can contribute.
Question for anyone who knows Git: Would it be like I learned in that basic Git video, where I create a branch, make my contributions, then request a merge back to main? I haven't tried fiddling with your code at all yet, so I don't know what I have access to, or how much of a repository's privacy settings are controlled by its creator.

tldr: Yeah, I can definitely try to contribute. No promises with how much or how soon, what with the school year starting back up here in the U.S. But I do love making tutorials.

Cheers,
-mango

[helgoboss]

It's done: https://github.com/helgoboss/helgobox/wiki

I have moved everything except the technical reference to a Wiki. I think a Wiki is the easiest way to let everyone contribute. It's not even necessary to dive into Git, you can change everything online (but it can also be edited locally and pushed via Git, your choice).

[helgoboss]

Big improvements on the documentation front: https://forum.cockos.com/showthread.php?t=295379