unfinished

Author: bast

content/installation.md

@@ -3,34 +3,47 @@
 [this page is adapted from <https://aaltoscicomp.github.io/python-for-scicomp/installation/>]
 
 
-## Packages that we will need
-
-In this course we will need **Python 3** and the following Python libraries/packages:
-- **jupyterlab**
-- **altair**
-- pandas (comes with altair)
-- vega_datasets (optional)
-- numpy (optional)
+## Choosing an installation method
+
+For this course we will install an isolated environment
+with following dependencies:
+```yaml
+name: data-viz
+channels:
+  - conda-forge
+dependencies:
+  - python <= 3.12
+  - jupyterlab
+  - altair-all
+  - vega_datasets
+  - pandas
+  - numpy
+```
 
+If you are used to installing packages in Python and know what to do with the
+above `environment.yml` file, please follow your own preferred installation
+method.
 
-## How to install Python
+If you are new to Python or unsure how to create isolated environments in
+Python from files like the `environment.yml` above, please follow the
+instructions below.
 
-We expect you to have a working Python installation with some common libraries.
-**We currently recommend Miniforge, which includes the base and packages
-through a different, freely usable channel.** You can explore the options in
-the tabs below.
+There are very many ways to install Python and packages with pros and cons and
+in addition there are several operating systems with their own quirks. This
+can be a huge challenge for beginners to navigate. It can also difficult for
+instructors to give recommendations for something which will work everywhere
+and which everybody will like.
 
-**If you are used to installing Python packages**, you can use your preferred
-installation method.  However, we recommend to not install the above packages
-system-wide and never to install using administrator privileges.
-Below we offer several options to install Python and the required packages
-from the [environment.yml file](https://github.com/coderefinery/data-visualization-python/blob/main/software/environment.yml).
+Below we will recommend **Miniforge** since it is free, open source, general,
+available on all operating systems, and provides a good basis for reproducible
+environments. However, it does not provide a graphical user interface during
+installation.
 
 :::{admonition} Python, conda, anaconda, miniforge, etc?
 :class: dropdown
 
-Unfortunately there's a lot of jargon.  We'll go over this in the
-course but here is a crash course:
+Unfortunately there are many options and a lot of jargon.
+Here is a crash course:
 
 * **Python** is a programming language very commonly used in
   science, it's the topic of this course.
@@ -55,6 +68,24 @@ course but here is a crash course:
   the Anaconda channels.
 :::
 
+
+## How to install Python
+
+We expect you to have a working Python installation with some common libraries.
+**We currently recommend Miniforge, which includes the base and packages
+through a different, freely usable channel.** You can explore the options in
+the tabs below.
+
+**If you are used to installing Python packages**, you can use your preferred
+installation method. 
+
+
+However, we recommend to not install the above packages
+system-wide and never to install using administrator privileges.
+Below we offer several options to install Python and the required packages
+from the [environment.yml file](https://github.com/coderefinery/data-visualization-python/blob/main/software/environment.yml).
+
+
 ::::{tabs}
   :::{group-tab} Miniforge
   This is our recommended method - it can be used for any purpose