add my suggestions

docs/user/transitioning_from_defaults.md

@@ -1,101 +1,125 @@
-# Transitioning from Anaconda's default packages
+# Transitioning from Anaconda's `defaults` channels
 
-Users wishing to transition from Anaconda's default channel should do so with
-care so as not to break their working environments. The first thing to realize
+Users wishing to transition from Anaconda's `defaults` (i.e. those hosted under
+https://repo.anaconda.com/pkgs) channels should do so with care so as not to 
+break their working environments. The first thing to realize
 is that in 2024 conda-forge is incompatible with the packages provided in
-Anaconda's default channel. Often, the packages on conda-forge will require
+`defaults`. Often, the packages on conda-forge will require
 newer versions of a particular package, or, may simply be organized in a
 different fashion. The only workflow we can support as a community is one where
 the conda-forge channel takes priority over all other channels.
 
-If you were using `miniconda3` or `Anaconda3` and wish to move to use
-conda-forge, we outline two workflow. The first allows you to try packages from
+If you were using Miniconda or Anaconda Distribution and wish to move to use
+conda-forge, we outline two workflows. The first allows you to try packages from
 conda-forge without uninstalling your previous installation, the second
-involves uninstalling `miniconda3` or `Anaconda3`, and only using conda-forge
-channels.
+involves uninstalling Miniconda or Anaconda Distribution, and then installing
+Miniforge.
 
 ## Trying conda-forge in an isolated environment
 
-1. Create a conda-environment with very strict dependencies. The following
-   command will only use packages from conda-forge to install Python 3.11. You
-   may adjust the version of python to the one of your liking.
+1. Create a conda environment with very few dependencies. The following
+   command will only use packages from `conda-forge` to install Python 3.11. You
+   may adjust the version of Python to the one of your liking:
 
-```bash
-conda create --name new_cf python=3.11 --channel conda-forge --override-channels
-```
+   ```bash
+   conda create --name conda-forge-env python=3.11 --channel conda-forge --override-channels
+   ```
 
-2. Activate your environment and add conda-forge with strict dependencies to
-   that particular environment.
+2. Activate your environment and add `conda-forge` with strict priority to
+   that particular environment:
 
-```bash
-    conda activate new_cf
-    conda config --env --add channels conda-forge
-    conda config --env --set channel_priority strict
-```
+   ```bash
+   conda activate conda-forge-env
+   conda config --env --add channels conda-forge
+   # optional:
+   # conda config --env --remove channels defaults
+   conda config --env --set channel_priority strict
+   ```
 
-3. Check the configuration of your conda environment.
+3. Check the configuration of your conda environment:
 
-```bash
-conda config --show
-```
+   ```bash
+   conda config --show
+   ```
 
-Should list out that conda-forge is the top most channel in your list.
+   This should report that `conda-forge` is the top most channel in your list.
 
-4. You are now in a position to use command likes
+4. You are now in a position to use command like:
 
-```bash
-conda install my_desired_package_from_conda_forge
-```
+   ```bash
+   conda install my_desired_package_from_conda_forge
+   ```
 
-## Uninstalling Anaconda3 and installing miniforge3
+## Uninstalling Anaconda and installing Miniforge
 
 If you are ready to fully switch to conda-forge, we recommend uninstalling
-Anaconda3 and installing miniforge3. The following steps are guidelines on how
-to go about this, while backing up your work and your environments.
+Anaconda / Miniconda and then installing [Miniforge](/download). The following steps 
+are guidelines on how to go about this, while backing up your work and your environments.
 
 1. Clean your existing conda installation. This should remove unused files from
-   your anaconda folder and make for smaller sized backup.
+   your Anaconda / Miniconda installation and make for smaller sized backup.
 
-```
-# The conda build purge command may fail if you don't have conda-build installed.
-# this is expected
-conda build purge
-conda clean --all
-```
+   ```shell
+   # The conda build purge command may fail if you don't have conda-build installed.
+   # this is expected
+   conda build purge
+   conda clean --all
+   ```
 
 2. Create a zip archive of your conda installation. Use your favorite graphical tool
-   to right click on the miniconda3 installation folder
-
-3. On windows, following the system uninstalling installation prompts to
-   uninstall Anaconda prompts to uninstall Anaconda3. On linux and mac, delete
-   the folder called `anaconda3`, or `miniconda3`.
+   to right click on the Anaconda / Miniconda installation folder. Check if you have
+   created additional environments outside the installation root by running
+   `conda info --envs`. Back those up too, if necessary.
+
+   - Alternatively, you can also export lockfiles for all your environments, if preferred:
+     ```shell
+     conda list --explicit --md5 --prefix /path/to/environment-name > environment-name.txt
+     ```
+     Note these lockfiles will only include the conda packages. If you `pip install`ed packages
+     on top, those won't be captured. Check [`conda-lock`](https://conda.github.io/conda-lock/)
+     for those use cases.
+
+   - Another useful file to create is the input `environment.yml` for each environment:
+     ```shell
+     conda env export --from-history --prefix --prefix /path/to/environment-name > environment-name.yml
+     ```
+     This file won't capture the exact same state you had in your environment. Instead it
+     will tell `conda` what packages to look for and then find a solution that satisfies
+     the request.
+
+3. On Windows, use the uninstaller suggested by the system control panel. 
+   On Linux and macOS, you can delete the folder called `anaconda3`, or `miniconda3`
+   (usually located in your home directory).
 
 4. Find the file called `.condarc` in your home directory, and back it up somewhere safe.
+   Then, delete your old `.condarc` file. A new one specific to conda-forge will be
+   created when we install Miniforge.
 
-5. Delete your old `.condarc` file. A new one specific to conda-forge will be
-   created when we install `miniforge3`.
+5. On Linux and macOS, your shell profile (`~/.bashrc`) might contain initialization code
+   from the previous installation. Locate the block guarded by `# >>> conda initialize >>>`
+   comments and delete it.
 
-6. Download and install the Miniforge3 installer that matches your platform from
-   https://github.com/conda-forge/miniforge
+6. Download and install the Miniforge installer that matches your platform from
+   the [Miniforge download](/download) page.
 
 7. Once installed, you should be able to use the `Miniforge3 Prompt` on
-   Windows, or the terminal on linux and mac, to run the command:
+   Windows, or the terminal on Linux and macOS, to run the command:
 
-```bash
-conda info
-```
+   ```shell
+   conda info
+   ```
 
-and notice that the conda-forge is the channel with the topmost priority.
+Notice that the conda-forge is the channel with the topmost priority.
 
 You should now be in a position to use conda-forge packages.
 
 ## A historical note
 
 Until roughly 2021, conda-forge held strong compatibility with Anaconda's
 default channel. However, due to the reasons outlined in XXXXXX, we decided to
-ultimately move away from dependency on Anaconda's default packages. Over the
-years, this has lead for more divergence between package versions, and names
-between conda-forge and Anaconda's default channel.
+ultimately move away from dependency on Anaconda's `defaults` packages. Over the
+years, this has led for more divergence between package versions, and names
+between conda-forge and Anaconda's `defaults` channel.
 
 In 2024, the workflow that has packages co-installed from Anaconda's channel and
 conda-forge is no longer supported.
@@ -108,5 +132,5 @@ conda list --show-channel-urls
 
 All packages should specify that they have been installed from the conda-forge
 channel. In 2024, there still exist a few bugs where conda packages will
-claim that they have been installed from PyPi even though they have been
+claim that they have been installed from PyPI even though they have been
 installed from conda-forge.