Onboarding both new and experienced programmers well

[kytrinyx]

The onboarding used to be horribly, absolutely, utterly broken. It was incomprehensible, and full of dead ends. It's no longer completely broken, but it's still not great.

I'm opening this issue in the hopes of finding ways of further improving the onboarding, including the option of scrapping what we have and trying something completely different.

When we were doing user research we learned that:

• experienced programmers were likely to successfully onboard, no matter how terrible the user experience was. They needed a quick overview, a link to download the client, and reassurance that the thing they were installing on their computer was not going to do nefarious things.
• newbies were thrown by almost everything. Jargon was intimidating. They weren't familiar with the command-line at all, they didn't necessarily know what GitHub was and why the hell Exercism had anything to do with that, and they'd end up on some random page to download the CLI and not understand where they were or what was supposed to happen next.

Also, it seemed like too much explanation/instructions frustrated experienced users, who basically knew the details, just needed to get it done.

I am worried that giving the same instructions to both groups of programmers. If we cater to newbies, the experienced programmers risk thinking that this is not for them, and being frustrated with the unholy level of detail. If we cater to experienced programmers, then newbies are likely to feel stupid and give up.

So as a first step in trying to address the broken onboarding, I decided to have two "how it works" pages. This might not be the best solution, but it did address some of the pain-points that we found when doing the user research.

@siakaramalegos noted in a discussion elsewhere:

I sometimes wonder if having separate sets of instructions for newbies vs experienced programmers helps. For one, I think it reinforces a fallacy that there is some high bar that is difficult to cross to become an "experienced programmer". When is that bar crossed? Secondly, I sometimes wonder if more experienced programmers are better at following directions or not. I think maybe they can troubleshoot bugs better, but not necessarily follow directions better.

These are great observations. I think that the biggest bar is context. Experienced programmers have a lot of it, newer programmers usually don't. As a result, I expect that one could give very short, compact instructions to experienced programmers, but not to newer programmers.

My impression is that the biggest barrier in all of this for new programmers is understanding PATH, though at the moment we aren't even really addressing that separately.

Another great comment from @siakaramalegos:

it might be even better if someone good at animations just created a few short (<1 min) videos explaining what exercism is and how it works/how to use it.

I'd love to have short video/animations.

Someone suggested using animated GIFs, and I have a problem with those, personally, because they are always moving and I can't think while they're in view. I also become physically unwell (I get the same thing with sites that have videos as the background to their homepages).

I have been thinking about how we could make an interactive guide to simplify the "CLI installation" portion of the onboarding. This is described in detail here: exercism/exercism#2535

[siakaramalegos]

It looks like a first-pass auto-detection of OS could be done with window.navigator.platform. There is also an oscpu property, but I couldn't get it to work in my browser.
https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/platform
https://developer.mozilla.org/en-US/docs/Web/API/Navigator

If you had maybe tabs on the same page for each OS, it might be pretty easy to use JS to autodetect OS and select the potential best tab. I would still put a sentence saying something like "We think you're using a Mac - if not, select the correct tab for your OS."

[kytrinyx]

Yepp, that sounds like a good approach. In fact, this would probably be a pretty low-effort first pass at reworking the CLI page on exercism.

[siakaramalegos]

Also, apparently there is a Ruby gem if you wanted to stick to Ruby - also does all the Regex to parse: https://github.com/fnando/browser

And a node package: https://github.com/ded/bowser

[kytrinyx]

I think that either way would be fine, so long as we make sure that if we don't have the information we provide a reasonable message/default (I don't know what this would look like with a text-only browser like links or lynx, or with a screen-reader for example.

[kotp]

A solution to the animated gifs, and a gentle introduction to the terminal... Not necessarily this ascicast, but the ways in which it can be applied.

For the places where the actual script is allowed, it has a play, pause, copy and paste functionality. All the good things ,none of the motion sickness and distraction inducing things.

[kytrinyx]

Nice! Yeah, if we can get gifs that let us play/pause/copy and paste, that's great.

I also think it would be lovely to have video that has animated diagrams for explaining at a high-level what exercism is about.

[kytrinyx]

Ref: #34

[kytrinyx]

Reference: http://theelearningcoach.com/learning/novice-versus-expert-design-strategies/

[troubalex]

Sorry for airdropping into the discussion, I just came across this issue after talking to @kytrinyx Bear with me, if I misunderstand or lack context. 🙇

Here are some suggestions and ideas, based on my experience designing for techies.

The most efficient way for experienced programmers is to give them a big download button, based on the OS they're on, provide a link to all the other packages, and tell them where to find the configuration instructions. It's probably fair to assume, they either know how to add stuff to their PATH, or at least know how to google for it. Ideally, the download button would actually start the download, rather than taking folks to Github, but I don't know how feasible that is without manually updating the link with every release. Which might be worth it.

To avoid a certain "real-developers-go-here"-effect which could scare the newbies, this could be achieved through a sidebar that holds the button and some kind of navigation for the different steps involved. Then experts can download their package and jump straight to the configuration step.

For new-beginners, it might make sense to create dedicated areas for installation instructions, e.g. "Install exercsim on Windows". That way, it is easier to divide up content, and provide the sidebar navigation which lets user jump to specific steps in the process at all times. Another side-effect could be a certain feeling of achievement at the end of each step. You might even provide a check-list showing progress.

It could also be a good idea to add (annotated) screenshots, especially for the Windows instructions, as finding the command line is not as straight forward as on other OSes. They are much faster and easier to make than screencasts, but still quite reassuring if you don't actually know what you're doing.

Then, I'd suggest simplifying the content for newbies even further. Right now, the instructions try to cover all cases which might be overwhelming. Is it possible to find one happy path, and move everything else into the troubleshooting section? For example, you could say that installation via Homebrew is recommended, and tell people to install that first if they don't already have it. Then you could link to a section within the troubleshooting guide that explains how to install the binary manually if you can't or don't want to use Homebrew.

I suspect that people get stuck with different problems anyway. The more experienced ones will google for a solution, but the other ones might need help. I saw in the Readme that there is a chat on Gitter, maybe consider making that more prominent inside the install guides. I didn't see it anywhere at least.

I would probably also move the biggest chunk of the detailed explanation which is now on the "how-it-works"-pages, into some kind of help section. That way, you can focus the copy on the "marketing-pages" on explaining your selling points for each target group. Currently, it's a mix of documentation, contextual explanation such as what Github is, and a feature overview. And there is a lot of text. 😉

I suspect that the newbie-version will need more explanatory copy than the other ones but that can be solved in different ways, e.g through well-phrased micro-copy, and/or an FAQ section.

Finally, what about moving all the instructions behind the sign-up? I don't remember what the first view looked like right after signing up, maybe it's already there. I imagine that what people most care about after signing up, is getting started. The welcome screen should therefore be the first one in the installation process. Having the user log in first also gives you the opportunity to provide the real API key inside the commands for easy copy-pasting.

I hope this makes sense, I'll happily draw some quick sketches if that helps. And sorry again for the huge brain-dump coming out of nowhere.

[troubalex]

PS: Take a look at this, in case you haven't already 👉 http://www.useronboard.com/

[kytrinyx]

@troubalex This is brilliant, thanks so much for the detailed suggestions!