CLI Installation Guide

[kytrinyx]

This issue is a UX, design, and front-end task

Right now getting the command-line client installed is incredibly confusing, and the documentation and troubleshooting guides are all over the place.

It would be absolutely lovely if we could have a "CLI installation guide" that would guide you through each step of installing and configuring the binary.

The suggestions below are just that--a starting point based on the current user interviews and support requests that come in.

• Detect your operating system (linux, windows, mac), or if unable to detect, let you choose.
• For each system have one suggested set of instructions to install, with alternate options listed discretely (e.g. for Mac the default option should be brew since it's dirt simple, but then you could have a discrete link or something that suggests an alternate approach if you don't have brew, or if you're comfortable with PATH etc, you can just download the tarball from GitHub and stick it in your path).
• If the installation steps require you to know which architecture you have (32-bit vs 64 bit) then the guide would tell you how to find out at the appropriate time.
• Show you how to configure the CLI (the example would be copy/paste-able if you're logged in, giving you your API key up front, and if you're logged out it would suggest that you log in, and tell you where to find the API key)

We would probably want to embed the guide into a section of the dashboard, and then when you've submitted a solution, tuck it away to somewhere findable/accessible, but no longer the main focus (since someone might want to set up a separate computer and might need to follow the guide again for a different platform).

[sguermond]

+1 for all of the above.
It should be front and center for first time users, and easily findable for users who want to install it on a new computer.

[mhelmetag]

It's times like these where I wish I knew more about frontend. I wonder how this would look... like an interactive slideshow? Not sure. A mockup could be fun to make.

[kytrinyx]

I keep hoping someone with frontend skills will be super-inspired to work on this. If not I'll have to finally go learn some proper design, HTML, CSS, and enough JavaScript to make it so.

[kytrinyx]

Ref: #2711

[ghost]

Katrina,
Ramya & I have tried the windows download, and we have the following feedback:
The following instructions are confusing:

The short version has doable actions in 1) + 2), but needs the full set of instructions for 3) which aren't obvious until scrolling down - it's easy enough to download + extract, but the path part is confusing.

so, instead, we're suggesting that the short version should be without links, and could be titled something like: 3 steps you'll be taking to download Exercism.

and then
go into the actual instructions.
What do you think? Keep as is, or change?

[ramyaravindranath]

Hi @kytrinyx

Re:Detect your operating system (linux, windows, mac), or if unable to detect, let you choose. Please clarify!

1. Do you want to give instructions about how to find out the system configuration to users?
2. Do you want to provide the download link which automatically downloads the binary to the given operating system ?

[ghost]

On the Mac OSX page "methods of installing CLI" I get:
"If everything is fine, you're done installing the CLI, and you can move on to the next step, which is configuring the CLI."
I'm wondering if everything to do with one method of installation eg:

• installing with homebrew,
• configuring the cli
• getting comfortable with the command line

should be grouped together on the one page, and when you're done, there's copy such as:
You're installed! Hooray! Get started with our language tracks.
@kytrinyx what do you think?

[kytrinyx]

so, instead, we're suggesting that the short version should be without links

Yeah, I think that's a good idea.

Re: Detect your operating system (linux, windows, mac), or if unable to detect, let you choose. Please clarify!

We should be able to figure out if they are on linux, windows, or mac, and automatically select the correct tab or page for them. They would still be able to switch to a different page/tab (however we end up doing it).

If we don't know what system they are on, we should have a default view that directs them to click on the correct link for their system (windows, mac, or linux).

Do you want to give instructions about how to find out the system configuration to users?

Yes, once they are on the correct tab or page for the operating system, we will still need to help them figure out if they have a 32-bit or 64-bit machine (for mac and windows). For Linux it might be 32-bit or 64-bit, but it might also be a raspberry pi, which means one of the ARM downloads.

Do you want to provide the download link which automatically downloads the binary to the given operating system ?

It's slightly more complicated than that... there are always things to choose from, so it won't be just one link. But I would like to provide links to download the relevant binaries; we need to provide more than one link, and as mentioned above, help them figure out which they need).

I'm wondering if everything to do with one method of installation eg:
should be grouped together on the one page, and when you're done, there's copy

Yeah, I think that we should walk you through step-by-step, and not confuse you with any other potential workflows. If you're doing the homebrew thing, then we shouldn't refer to any of the other installation methods as part of the workflow. We should probably have small print that lets them choose a different installation method, but that's a separate problem :)

[ghost]

@kytrinyx @troubalex
Mockup below of how the page could look - removing the overview, having the basic information for an install, and putting Mac osx first (website statistics show that's the most popular operating system for exercism.io). I'm putting the copy together, and fine to provide that as documents to review, or open to suggest as to how to provide text for review - another issue, or add to this one perhaps?

[troubalex]

A couple of comments/questions:

• I like the more simplified version of this, it is much less intimidating.
• What are your reasons for moving the tabs to the top instead of keeping them on the right hand side?
• Where should the more advanced instructions go, such as installing without Homebrew? How would you want to make people aware of their existence?
• Have you considered moving the instructions to dedicated pages for their respective OS (see my comment in this thread)? How might that look? Could you draw a quick paper sketch?
• The page would benefit from a better vertical rhythm. Especially, the margins below the code snippets are practically non-existent. Could you have a look at how this could be improved to give the page a clearer structure?

I cannot comment so much on the copy itself, but I suggest you use public gists which you can link to from here. There you can use markdown for structure and formatting which will make it easy to transfer the content afterwards. A more detailed discussion can then happen in the context of each gist.

[ghost]

@troubalex

I like the more simplified version of this, it is much less intimidating.

thankyou - that's the aim.

What are your reasons for moving the tabs to the top instead of keeping them on the right hand side?

I wanted to make downloading the CLI cleaner and simpler, and felt that nav at the top helped with that.
There's code blocks, and when you have that left hand nav, the chances of needing to scroll horizontally in order to see/get a code block are higher, depending on your screen resolution. I noticed that the code blocks in languages didn't have the side nav, only the top, perhaps for the horizontal scrolling reason, so I'd like to adopt the code/layout from those pages:
http://exercism.io/exercises/csharp/bob

Where should the more advanced instructions go, such as installing without Homebrew? How would you want to make people aware of their existence?

Where you've recommended in your comments in the thread - into a troubleshooting page. I plan to have links to the troubleshooting page along with gitter at the top (and bottom?) of each install page.

Have you considered moving the instructions to dedicated pages for their respective OS (see my comment in this thread)? How might that look? Could you draw a quick paper sketch?

I'm not quite sure what you mean... in that the instructions are in dedicated pages visually now. Will bring that up with you off github. What I have done is a quick drawing of a potential flow of info:

The page would benefit from a better vertical rhythm. Especially, the margins below the code snippets are practically non-existent. Could you have a look at how this could be improved to give the page a clearer structure?

Agreed, and that CSS is tricky - I'll write up a separate issue about it, as I'm concerned about where else the margin issue is, and the ramifications (eg maybe it's like that for a reason for viewing code in the dashboard? I don't know. There's other pages using that code such as help, so it would be good to know how large a project that is before getting started.

I cannot comment so much on the copy itself, but I suggest you use public gists

thanks - taken on board, and will provide when done.

[troubalex]

There's code blocks, and when you have that left hand nav, the chances of needing to scroll horizontally in order to see/get a code block are higher, depending on your screen resolution. I noticed that the code blocks in languages didn't have the side nav, only the top, perhaps for the horizontal scrolling reason, so I'd like to adopt the code/layout from those pages:
http://exercism.io/exercises/csharp/bob

I don't think it's possible to avoid horizontal scrolling in all cases, and that's okay. The tabs in the sidebar break onto the top on smaller screens, thanks to Bootstrap's responsive grid, so that's not an issue either. Consistency however is. 👍

What I have done is a quick drawing of a potential flow of info

That makes sense to me.

[ghost]

@troubalex - here's the gists for each section:

• cli_macosx
• cli_windows
• cli_linux
• cli_troubleshooting

I really need to get these working locally, as I'm finding it difficult to work out what's missing etc in gist/markdown form, and it would be great to have the website locally to work through. What are your thoughts? Let's talk offline and work out next steps.

[troubalex]

The structure looks good to me.

I can't really comment on the content though, we'll have to make sure to get an extra round of proofreading once this is ready for a PR.

As you suggested, I'd move on to making the actual pages, and then we take it from there.

[ghost]

I've made the pages, and will provide a PR - I just need to go over the links/formatting.
Here's the screenshots of each page from my local files:
Mac:

Windows:

Linux:

Troubleshooting:

[ghost]

There's the open pull request: #3089
I think the next stage after that is what I'm aiming to do in a new pull request next week:

[] Detect Operating System and redirect to appropriate OS as discussed in issue 2535
[] Add new windows installer. (#3077 (comment))
[] Creating partials of repeated information eg: accessing help, and continuing to languages.

[kytrinyx]

In the future, would you please put the screenshots in the pull request, not in the original issue? I didn't see this until after I had reviewed the pull request.

The general rule of thumb for pull requests is to put everything that the reviewers would need right there—link to other places for more information, but people shouldn't have to follow the links to get the most important bits.

Side note: checklists in markdown are made like this:

- [ ] list item one
- [ ] list item two
- [ ] list item three

[kotp]

Related: #3332

[kytrinyx]

The CLI documentation has been massively improved since I originally posted this. I'm going to go ahead and close this, and we can revisit the idea if it becomes clear that it would be a big improvement.