Add conda install/setup instructions

[sjspielman]

Which issue does this address?

Closes #122

Briefly describe the scope of the added docs file, including whether you link out to any external docs.

This file adds conda installation and setup instructions. I open with some short descriptions of what conda is and why we want to use it, with short sentences, lots of spacing, and ample bullets!

Some of it is a bit different from CONTRIBUTING since, as discussed with @jashapiro, the behavior in those commands turns out to not exactly be what we want. The steps included here reflect our separate conversation.
Because of this change, steps for mac/pc are now more similar than they otherwise might have been since interaction with terminal+conda prompt will look about the same. Therefore, I only have 1 setup section here.

Will you need additional visual aids for these docs?

Yes - we will need some Windows screenshots. I plan to open a separate issue to circle back to this later once we get our hands on a PC. Related, there is also a spot where I need to explain how to open the conda prompt, which will also happen once we get that PC.

Any other comments for reviewers?

• I'm requesting review from @jashapiro for content, and @dvenprasad for feedback on whether I've provided the right kind of information for a conda newcomer to feel comfortable.
• I wonder if we want an additional section at the bottom for more advanced users and if so what that section might contain besides "make sure you have these three packages installed"
• Note the info note! Do we need it? What should go in it? The text I have there is of course a placeholder.
• Edit - is "bucket" too jargony? I figured they will have to encounter this term but maybe I am wrong!

Author checklist

• The docs page has been added to the nav section in mkdocs.yml
• The docs adhere to the style guide structure directions?
• The docs adhere to the style guide language directions?
• The docs adhere to the style guide tone directions?

Reviewer checklist

Please refer to the docs style guide while reviewing this pull request.

• Do the docs adhere to the style guide structure directions?
• Do the docs adhere to the style guide language directions?
• Do the docs adhere to the style guide tone directions?

[jashapiro]

Looks good. I suggested a few smallish changes.

I think if we are going to introduce people to the Terminal app for the first time, we probably want to do that on a separate page, with more context. Maybe a link here out to a tutorial for command line beginners? Not necessarily our own.

[jashapiro]

I'm not sure we need these instructions? If somebody is coming in never having used the terminal, diving into conda may not be the best place to start.

[sjspielman]

If somebody is coming in never having used the terminal, diving into conda may not be the best place to start.

truer words have not been said

[sjspielman]

I've replaced this with a STUB_LINK to a TBD docs page about "what is the terminal"

[sjspielman]

I think if we are going to introduce people to the Terminal app for the first time, we probably want to do that on a separate page, with more context. Maybe a link here out to a tutorial for command line beginners?

I think this might tie in well with some of the discussion in this PR - #36. What do you think?

Apple actually has some decent docs -

• https://support.apple.com/guide/terminal/what-is-terminal-trmld4c92d55/2.14/mac/14.0 (I find the Note at the bottom a little amusing, but certainly not wrong)
• https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/2.14/mac/14.0 - maybe with this we don't need the screenshot of spotlight, but it also doesn't hurt to keep?

Curious what you think of some of these -

• https://www.makeuseof.com/tag/beginners-guide-mac-terminal/
• https://macpaw.com/how-to/use-terminal-on-mac
• https://www.youtube.com/watch?v=dWFMRp6KtlQ
• https://www.youtube.com/watch?v=aKRYQsKR46I (caveat, I am anti nano)

[dvenprasad]

Just had one comment about the note admonishment. Otherwise all else looks good!

[dvenprasad]

The two admonishments one after the other is too much. The note doesn't really need to be in the box. It can go after the code block. It can be bolded at the most.

[sjspielman]

thanks for the feedback!! I'm very happy to hear overall that the page was (presumably) approachable!

[dvenprasad]

Yeah it was approachable, uses the right terms for the right OS ✔️ , easy to follow steps ✔️

Oh oH! this might be a nice to have - maybe a "success" screenshot.

[sjspielman]

Yeah, I was thinking that. I also was thinking we might want to show a screenshot of the "good expected" output that conda spits out while it's working. Thoughts?

[sjspielman]

FYI I made the info bullets, and I ended up moving the note admon to the next step where it more properly belongs. I also added a "success" screenshot into the next step, since there isn't any specific output for setting the channels

[jashapiro]

Looks good.

The Windows stuff is definitely worth a separate pass. I think we may also want to note somewhere that the primary platform for the project is linux, and not all modules will be guaranteed to work on Windows.

[jashapiro]

I might replace all of this with maybe just a note (collapsed by default?) for if you are new to the terminal. Maybe something like:

??? info "New to the terminal?"

    If you are new to the terminal, you will probably want to start with a more general introduction. 
    Here are a few we recommend:

    - [How to Use Terminal on a Mac: A Beginner's Guide](https://www.makeuseof.com/tag/beginners-guide-mac-terminal/)
    - ...

I like the makeuseof.com link best of what was there.

I actually don't think we should show Spotlight. I know people who never use Spotlight and would find that even more confusing than just instructions on where to find it in the Applications folder. It is fine to mention it as an option (I know, one way to do it), but the screenshot seems overkill. I might phrase it as "The Terminal application is located in the Utilities subfolder of Applications, or you can get to it by searching for "terminal" in Spotlight or Launchpad.

[sjspielman]

I might replace all of this with maybe just a note (collapsed by default?) for if you are new to the terminal.

I'm not sure how I feel about this re-Windows, because we have to distinguish between the Windows terminal (whatever that is) and conda itself. So, just "open a terminal" won't be enough information for Windows. Am I missing something?

[jashapiro]

If Windows is the special case, then it will need a callout, but I would put that off until we do some Windows testing, is basically what I am saying.

[sjspielman]

I might replace all of this with maybe just a note

Oh, I thought "all of this" meant both windows and mac, but you just mean mac?

[jashapiro]

As far as I can tell, it should work on windows in Powershell and cmd.exe, the default prompt: https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html

[dvenprasad]

LGTM
🐍 🐍 🐍

[sjspielman]

See here: 3c1c57b

I also included one of the videos I liked

[jashapiro]

With the caveat that things might change with windows testing, LGTM.

[jashapiro]

I can see this evolving to move these to a link to another document, but this is good for now.