[Help Needed] Working out CLI install workflows

[iHiD]

Hi everyone. We need some help!

As part of the new website we want to build comprehensive instructions that make it really simple for beginners and experts to install the exercism CLI and download exercises. Depending on experience this ranges from something like brew install exercism && exercism download bob to "This is what a terminal is..."

There's loads of content spread around on the current site, from language installation instructions to how to install the CLI. We want to to turn this into a series of questions and answers that are easy to walk through. For example:

• What OS are you on (3 buttons)
• Do you have Homebrew installed? (Yes, No, I have no idea what Homebrew is)
• Do you know what a terminal is? (Yes, No)
• Run this command on the terminal...
• Do you care about understanding what this command does? (you'll never need to run it again)

etc etc

We need some volunteers to work out what these flows look like for Windows, Mac, and Linux. We'll then put them together into a master flow on the website.

Doing this requires the skill of understanding all the things a beginner would have no idea about, and also a knowledge of how to install everything on your OS. We also need this done asap (within 7 days).

If you'd like to volunteer to help, could you please say so below and then we'll move add you to a repo where we can work this all out. We'd be very very grateful! :)

[HarrisonMc555]

I can help with Linux and/or Windows (I have access to both). I have little brothers who can be guinea pigs to see if they understand the instructions for beginners 😄

I'm more familiar with Linux development tools but I could probably figure out stuff for Windows, too. I solve exercism exercises in both.

[m-dango]

I can help with Linux.

[iHiD]

@HarrisonMc555 @mienaikage Thank you both.

So I think the first step would be to go through the instructions at http://exercism.io/clients/cli/linux and check they are:

• Fully functional (do any steps break)
• Complete - (are there any steps missing)

Then the next key thing is to highlight all the things that might block a beginner. For example, are the instructions at https://chocolatey.org/install usable for a beginner. One of the first lines is "Copy the text specific to your command shell" - does a beginner know what a command shell is and how to get it it?

Once we've got all that information down, I think the key deliverable is a flowchart of knowledge (as I tried to explain in the initial post).

Does that sound like a sane approach?

[m-dango]

That sounds like a sane approach, although I'd suggest also checking whether steps are necessary.

[catb0t]

I'm on board for Windows 10, Windows 7, and desktop Linux.

[NobbZ]

For example, are the instructions at https://chocolatey.org/install usable for a beginner.

They aren't, but at least they are canonical!

We held that discussion before, and it is a complicated thing.

[iHiD]

If they're not usable then we need to work out how to make them usable then. Which bits don't make sense to a beginner and how can we help a beginner through that?

[NobbZ]

There are this paragraphs:

With PowerShell, there is an additional step. You must ensure Get-ExecutionPolicy is not Restricted. We suggest using Bypass to bypass the policy to get things installed or AllSigned for quite a bit more security.

Run Get-ExecutionPolicy. If it returns Restricted, then run Set-ExecutionPolicy AllSigned or Set-ExecutionPolicy Bypass.

They have improved since I installed choco by myself, but they appear to be an unimportant side note.

Also I feel as if the hole page were out of order (in a sense that stuff is not written one after the other, but in random order).

We once had an explanation of how to install choco on the website, but it got out of sync with the way choco was actually installed. We had about one broken choco install because of that per day in gitter.im/exercism/support. Some of them where broken in a way that involved very hard debugging sessions or even RDP sessions for actually helping to remove the partially installed choco and recovering the system into a state that was "clean enough" to start from scratch.

Since those instructions were removed we only have about a single one per month asking about how to install choco. Since those people haven't broken their system until then it is a matter of minutes to help them out.

So I stick to my opinion, that chocos instruction aren't clear, but at least clear enough and also they are the only canonical description of how to install choco!

[rpottsoh]

I was looking at the Choco instructions provided for the Windows client. It seems to me that Choco should be documented as an optional tool for install/updating the Windows CLI.

In the meantime I thought I would try out the Windows Installer for the CLI. It won't work for me, so I have created issue #13 in the windows-installer repo.

[kytrinyx]

It seems to me that Choco should be documented as an optional tool for install/updating the Windows CLI.

I think this would make sense. I would really like us to have a simple, beginner-friendly way for anyone to install Exercism. For people who already have Choco, then that is probably a good choice. But if not, then maybe we can come up with something better. If we could get the windows installer working, that might be a good choice. Or something else—like I said, I'm not so particular about which approach we choose, only that we find a way to lower the barrier for folks who might never have interacted with the command line before.

[iHiD]

@NobbZ Thanks for giving us some background on this.

So I stick to my opinion, that chocos instruction aren't clear, but at least clear enough and also they are the only canonical description of how to install choco!

It strikes me that the problems with the choco instructions are around using language that a beginner might not be familiar with (e.g. "Command Line"). If we can highlight those terms, then we can explain them to a beginner before pushing them to that file. That then means we can have canonical instructions, but also demystify them in advance.

Since those instructions were removed we only have about a single one per month asking about how to install choco.

This could just as easily mean we only have one total beginner per month installing Exercism on Windows now because they find it too difficult to do. I'm not sure that it's a good measure of whether it works or not, although I understand that it's a good thing that it's reduced the burden of maintainers on gitter.

[HarrisonMc555]

@iHiD I'm not sure if there was a particular place you wanted me to provide feedback, so I'll do it here unless otherwise directed.

Linux CLI install workflow

Functional Check

From what I can tell, the instructions are both

• Complete, and
• Fully Functional

Beginner stumbling blocks

To get a good perspective on how a beginner would feel, I got my 13-year-old brother (who has never used Linux) to try to get started using exercism. I had him start on the home page, but he quickly found his way to the Linux CLI installation page.

Unfortunately, he got stuck pretty quickly, and even after trying for 10-15 minutes he wasn't able to figure out what to do. Eventually I gave him a few pointers which helped him get through. Here are some of my observations:

• He was confused by the fact that there were two links right next to each other that led to the same place under "Installing the Command Line Client".
• He wasn't sure what he was supposed to do or where to start on the Linux CLI installation page.
• He mentioned "It keeps showing the codes, where do I use these codes?" (referring the the CLI snippets).
• He went back and forth between the How it Works: For New Developers page, the Linux CLI installation page page, and the CLI Downloads page page.
• He was confused by the fact that the title for the CLI Downloads page (when we visited it) seemed to be titled "Fix upgrade command on Windows". I could tell that that he thought he might be in the wrong place since he was trying to download the CLI for Linux, not Windows.
• He didn't know what a "processor architecture" was or how to find out what he had. I don't think he made the connection between the processor architecture line and the names of the download files on the download page.
• He didn't understand this line:

  E.g. if your shell is bash, you could run:

• After I pointed out the first blurb on How it Works: For New Developers ("You'll see many references to Command-Line Client..."), he visited Learn Enough™ Command-Line to be Dangerous but didn't get too far before getting a little bored.
  • He probably didn't realize that the tool he was trying to download would live in the command line, and thus didn't realize that he really did need to know something about how the command line worked.
• Even when I prompted him to Google "What is a cli?" and "How to use the Linux command line?", he still didn't know how to open the command line (or even the fact that it was a something you could "open").
• He would have given up if I had not stepped in and given him hints and pointers.

Suggested Flow

My suggested flow for Linux would only include one question:

Are you familiar with the Command Line?

• Yes
• Not really
• I don't know what that is

Yes

• Current instructions

Not really

• How to find your processor architecture (uname -m)
• Find your architecture in download page
• Navigate to where you downloaded the file
• Templated tar example (instead of default 32-bit filename)
  • E.g. tar -xzvf EXERCISM_DOWNLOAD_FILENAME.tgz
• Place binary in path (same as current)
• Add to shell configuration echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
  • Don't include the "E.g. if your shell is bash..." line. I think we can assume if someone is using something other than bash then they know enough to know what to do instead
• No "Package Managers" line (people using those Linux flavors aren't likely beginners)
• Verification instructions (same as current)
• CLI configuration instructions (same as current)
• Setting up Exercism CLI completion instructions (same as current)

I don't know what that is

• Brief explanation of what a command line is
• How to open the command line
  • Possibly include screenshots from common Linux desktop environments
• 2-3 basic command examples
  • pwd
  • ls
  • cd
• ...same as "Not really" instructions

[kytrinyx]

@HarrisonMc555 this is amazing. I have no useful feedback only holy shit thank you 🌷 🌷 🌷

[iHiD]

@HarrisonMc555 Thank you thank you thank you. This is super-helpful!

[NobbZ]

@HarrisonMc555 I like your detailed report, and I really welcome the courage of your brother to be the “lab rat” for you ;) I do hope, that touching linux didn't do him any permanent harm ;)

But I do not think, we should blow up linux instructions into even more sub-pages.

Instead just give instructions for enabling system specific repositorys to install via yum, apt, emerge[1], pacman, or whatever we want to include.

As a last resort, we should provide a simple script, which one can download and run, which then does the following:

1. tries to detect what go would use as values for $GOOS and $GOARCH (isn't fetch-configlet already doing something similar?)
2. download the appropriate build from latest release
3. untars it into a temporary folder
4. copies the cli into $HOME/bin
5. checks the $PATH if $HOME/bin is available and updates the rc-file of the currently running shell (if it is a known one, show warning instead if not[2])
6. optional ask for the API key and activate installation

We could advertise this, as a non-root or local install, which might be necessary for some people. Not everyone will be able to do systemwide installs.

[1]: I try to maintain a portage overlay at https://github.com/NobbZ/gentoo-overlay for personal use, which also includes app-misc/exercism-cli.

[2]: I think providing official support for bash and zsh should be enough, whoever uses something else, will probably know what he has to do when a message pops up telling to add something to $PATH.

[HarrisonMc555]

@kytrinyx @iHiD @NobbZ glad you found this helpful!

@NobbZ I understand your reluctance to split the Linux instructions into sub-pages, but I'm going to stand by my original suggestions. I still go to the difference between me and my brother as the reason.

If I started with exercism and had to wade through all of the information I suggest under the "I don't know what that is" section then I would find it really tedious. My thoughts would be "just show me a tar xvf exercism-linux-32bit.tgz && mv exercism ~/bin.

However, if you removed all of the helpful information, you return back to the state that we're currently at where beginners have no idea where to start or even where to look for help. At one point my brother Googled "Getting started with exercism" or something to that effect because he had no idea what to do.

I think it would be quite beneficial to have different tracks for different degrees of familiarity for each OS. We've already decided to make different installation instructions for "beginners" and "experts", but that is before you go down a specific "OS track". I'm suggesting pushing down the beginner/expert distinction into the "OS tracks". It makes sense to do this since there are a lot of OS-specific instructions that we need to include for "beginners" that we don't need to include for "experts".

I do agree that using apt, yum, or pacman would probably be the ideal solution, as long as the packages were kept relatively up-to-date. If they consistently are really old then it may not be ideal.

[HarrisonMc555]

@NobbZ I forgot to reply to your suggestion of the "last resort" script...I'm not sure if I'm a fan of that. Mostly because I would feel hesitant to alter the user's .bashrc or .zshrc and $PATH without being sure they're explicitly aware of what is happening. For a beginner it may be helpful to just get something working, but anyone somewhat familiar with the command line might feel like that was touching their "personal things" (at least that's how I would feel).

Is it too much to ask for a beginner to:

• Extract a file
  • tar -xzvf exercism-linux-32bit.tgz
• Move the extracted executable to ~/bin
  • mkdir ~/bin && mv exercism ~/bin/
• Add ~/bin to the $PATH
  • export PATH=$HOME/bin:$PATH
• Permanently add ~/bin to the $PATH in a configuration file
  • echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc

This is what we already ask users to do in the current instructions.

The benefits I see to having beginning users explicitly type/copy and paste these in the command line is that

1. They will remember what they did (at least vaguely)
2. They will begin to be more familiar with common command line concepts (e.g. $PATH, .bashrc, etc.)
3. They will know where the file is if they want to delete it
4. They will know what they did to their computer (even if they don't completely understand what it means yet)

[NobbZ]

Of course I do not say, that our install page should simply say "run curl url_to_installer | sh". I am open for a well thought description around that.

BUT, I had some talk with my father tonight, whom I showed the install page as well. He is using linux for about a year now, but GUI only. He was aware of the existence of the shell, but simply doesn't use it, since there is enough tooling available for him to avoid it.

I asked him to at least take a look at the page.

He told me, that it is far to much text, and suggested a short oneline installer as well.

Folks wan't to get things up and running, not study CS just to install a small tool, which most of us do only use a subset of its functionality of.

Perhaps we can have something like this:

To install exercism for you as the only user having it available, please do the following steps:

1. Open up your terminal
2. Run curl ... | sh
3. Reopen your terminal and start using exercism

The script will do the following things, which of course you can do on your own, if you wan't to learn to know your system:

[explanation of the internals of the script in a way to manually follow the steps]

Also I do not think we should explain how to open a terminal. The user will already know how to start a program on his DE, and we can't cover them all. There are quite to many.

Also we should provide very precise comments in the script.

---

You are right, altering the users rc-file without asking might be considered rude, but we could ask if we are allowed to.

[kytrinyx]

One of our goals with reworking all of this is to hide all the text that someone doesn't need to see now or yet or at all.

This will vary from person to person, and in order to achieve this we need feedback about (1) whether or not the current instructions are complete and correct, and (2) how different people react to them so that we can start seeing patterns.

Right now we're not making decisions about how to solve it, we're trying to figure out what the underlying constraints are, and what our options are.

[m-dango]

I stumbled upon AppImage for the first time today. It looks like it could be quite handy for the Linux CLI install process.

[NobbZ]

Since go-binaries are usually statically linked and have no runtime dependencies, we do not need an additional layer of packaging.

For AppImage there needs still to be choosen between 32 and 64 bit, and AFAIK it won't work on ARM. So it wouldn't change anything, we had 6 different linux builds to choose from.

[kytrinyx]

We've got this sorted, thanks to a whole host of helpful contributions.

If you want to see it in action check out https://exercism.io/cli-walkthrough and if you want to contribute improvements check out https://github.com/exercism/interactive-cli-walkthrough