Improve copywriting for Installation

source/installation/index.md

@@ -3,7 +3,7 @@
 ```{toctree}
 :hidden:
 
-howto-web-no-local-install
+on-the-web
 howto_docker
 offline-environment
 windows-no-admin
@@ -12,12 +12,12 @@ test_situations
 
 As the OpenFisca community becomes larger, issues that only affect a small percentage of users arise.
 
-The purpose of this section is to bring together the clever solutions the community came up with and share them with all OpenFisca users.
+The purpose of this section is to bring together clever solutions the community comes up with and share them with all OpenFisca users.
 
-- [How to use OpenFisca on the web (no installation required on your computer)](./howto-web-no-local-install.md)
+- [How to use OpenFisca on the web (no installation required on your computer)](./on-the-web.md)
 - [How to use OpenFisca with Docker](./howto_docker.md)
 - [How to install OpenFisca in an offline environment](./offline-environment.md)
 - [How to work on OpenFisca on a Windows without being administrator](./windows-no-admin.md)
 - [How to test your changes on "ready to use" situations](./test_situations.md)
 
-> You're welcome to share your tips on how to solve technical issues! Please update [this section](https://github.com/openfisca/openfisca-doc/edit/master/recipes.md) (in English) or this [wiki FAQ](https://github.com/openfisca/tutorial/wiki) in your preferred language.
+> You're welcome to share your tips on how to solve technical issues! Please suggest updates, create pull requests in this [section](https://github.com/openfisca/openfisca-doc/edit/master/recipes.md). Note: it is intended this documentation is in English.

source/installation/offline-environment.md

@@ -1,61 +1,68 @@
 # In an offline environment
 
-If you need to install OpenFisca on a server with no Internet access, here is how to do it.
+If you need to install OpenFisca on a server with no internet access, here is how you might do it.
 
-The big picture: download Python packages on a machine with Internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/).
+The big picture: download Python packages on a machine with internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/).
 
-We assume that it is possible to copy files to the server, for example via a USB stick. Or perhaps the server filters only outgoing connections, but accepts incoming connections allowing to copy the files.
+It's assumed that it is possible to copy files to the server, i.e. via a USB stick.
 
 ## On the machine with Internet access
 
-We are going to create a first virtualenv in which we'll use `pip` to download the `.whl` files in a specific directory.
-
-Here we use [pew](https://github.com/berdario/pew) to simplify virtualenv management.
+First create a virtual environment and use `pip` to download the `.whl` files to a specific directory.
 
 ```sh
-pip install pew
-pew new openfisca-packages --python=python3.7
+mkdir ~/openfisca-packages
+cd ~/openfisca-packages
+
+# Create and instigate a virtual environment
+python3.11 -m venv .venv
+source .venv/bin/activate
 
 # Upgrade pip itself
 pip install --upgrade pip
 pip --version
-# Should print at least 9.0 at the time we write this doc.
+# Prints 24.0 at the time this doc was written.
 
-mkdir ~/openfisca-packages
-cd ~/openfisca-packages
-pip download OpenFisca-France
+mkdir country-template
+cd country-template
+pip download OpenFisca-Country-Template
 # You should see the downloaded files in the current directory.
 ```
 
-Now copy these files on the server (say in the `~/openfisca-packages` directory), either via a USB stick, or with `scp`, or any other way.
+Copy the files in the `~/openfisca-packages/country-template` directory to the server via a USB stick, or for example with `scp`.
 
 Example with `scp`:
 
 ```sh
-scp -r ~/openfisca-packages user@server:
+scp -r ~/openfisca-packages/country-template user@server:
 ```
 
 ## On the server
 
-Starting from here we assume you copied the packages on the server, say in `~/openfisca-packages`.
+The following assumes the files are now stored in `~/openfisca-packages/country-template` on the server.
 
 The following commands show how to install Python packages without any Internet access.
-If you already have a virtualenv, activate it. Otherwise create a new one following the same instructions as above (for example with `pew new`).
+If you already have a virtual environment, activate it. Otherwise create a new one following the same instructions as above.
 
 ```sh
-pip install ~/openfisca-packages/*
+    pip install ~/openfisca-packages/country-template/*
     Processing ./isodate-0.5.4.tar.gz
     [...]
-    Installing collected packages: pytz, Babel, Biryani, numpy, PyYAML, OpenFisca-Core, requests, OpenFisca-France, isodate
-    Successfully installed Babel-2.3.4 Biryani-0.10.4 OpenFisca-Core-7.0.0 OpenFisca-France-15.1.0 PyYAML-3.12 isodate-0.5.4 numpy-1.12.0 pytz-2016.10 requests-2.13.0
+    Installing collected packages: StrEnum, sortedcontainers, typing-extensions... openfisca-country-template
+    Successfully installed StrEnum, sortedcontainers, typing-extensions... openfisca-country-template
 
-pip list | grep OpenFisca-France
-    OpenFisca-France 15.1.0
+    # Step completed, the following can be utilised to confirm success and versions of the packages installed.
+    pip list | grep openfisca-country_template
+    openfisca-country_template 7.1.1
+
+    pip list | grep OpenFisca-Core
+    OpenFisca-Core 41.4.5
 ```
 
-Run the basic tests which confirm that OpenFisca-France is correctly installed:
+To check that everything works correctly, run the following command:
 
 ```sh
-python -m openfisca_france.tests.test_basics
-OpenFisca-France basic test was executed successfully.
+python -c "from openfisca_country_template import CountryTaxBenefitSystem; CountryTaxBenefitSystem()"
 ```
+
+No error message should appear. You can now utilise this environment to [run simulations](../simulate/run-simulation.md).

source/installation/on-the-web.md

@@ -0,0 +1,24 @@
+# On the web
+
+Some online services offer the opportunity to run Python code without having to install anything on your machine.
+
+For example, if you wish to evaluate the impact of a reform you could decide to run an OpenFisca simulation directly in your browser. To achieve this you might find one of the following services useful: [Gitpod](https://www.gitpod.io/), [repl.it](https://repl.it), [python anywhere](https://www.pythonanywhere.com) and [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/).
+
+Please be aware that you will need to install the OpenFisca package you need on your online service before using it. You will find a quick generic usage example to test your setup below.
+
+## Instructions
+
+1. Start by installing the package you need on your online service e.g. `pip install openfisca-country-template`.
+
+2. Write the code you wish to run. The following code snippet works with the above package:
+
+    ```py
+    from openfisca_country_template import CountryTaxBenefitSystem
+
+    tax_benefit_system = CountryTaxBenefitSystem()
+    parameters = tax_benefit_system.parameters
+
+    print(parameters)
+    ```
+
+3. Run your code and check the results.

source/installation/test_situations.md

@@ -1,7 +1,6 @@
-# How to test your changes on "ready to use" situations (for OpenFisca-France)
+# How to test your changes on "ready to use" situations
 
-Often, when making changes to legislation, you need to test it on a situation that works with your country's tax and benefit system.
-Sometimes, these situations can be quite complicated to model (such as roomates).
-Instead of re-writing them everytime, we have pre-packaged a few in a Python Package.
-
-You can find the package along with a usage example in the [Tutorial repository](https://github.com/openfisca/tutorial/tree/master/python/scripts/generate_situation_examples)
+Often, when making changes to legislation it needs testing on a simulation that works with your country's tax and benefit system.
+Sometimes, these simulations can be quite complicated to model.
+Instead of rewriting them every time, first check your country's repository for `situation_examples` that have already been created. 
+If what you need does not exist, you could create your own examples and contribute them to the repository.

source/installation/windows-no-admin.md

@@ -13,20 +13,20 @@ Git is a tool that will help you version your work. It also comes with a shell *
 
 ## 2. Install Python
 
-Python is the programing language used in OpenFisca. It can be installed without administrators rights through a software named Miniconda.
+Python is the programming language used in OpenFisca. It can be installed without administrator rights through a software named Miniconda.
 
-- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose the **Python 3.7** version for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit.
-- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, but in all case **copy paste the path to this folder somewhere**. It will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`.
+- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose the **Python 3.11** version for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit.
+- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, in any case **copy-paste the path to this folder somewhere** as it will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`.
 - Run the program "Git Bash" from the "Start" menu. This should open a command line. Copy and paste the following lines in the console, after **adapting the first line using the path you noted in the last step**:
 
 ```sh
-echo 'MINICONDA_PATH="C:\Users\form\AppData\Local\Miniconda2"' >> .bashrc
+echo 'MINICONDA_PATH="C:\Users\my-name\AppData\Local\Miniconda2"' >> .bashrc
 echo 'function convert { echo /$1  | sed '\''s/\\/\//g'\'' | sed '\''s/://'\'' ; }' >> .bashrc
 echo 'function add { export PATH=$(convert $1):$PATH ;}' >> .bashrc
 echo 'add $MINICONDA_PATH' >> .bashrc
 echo 'add "$MINICONDA_PATH/Scripts"' >> .bashrc
 source .bashrc
-conda create -n openfisca python=3.7  --offline --yes
+conda create -n openfisca python=3.11  --offline --yes
 echo 'source activate openfisca' >> .bashrc
 source activate openfisca
 ```
@@ -41,12 +41,14 @@ A version number should be printed, and no error message should appear. Congrats
 
 ## 3. Install OpenFisca
 
+For this example, we will utilise the `OpenFisca-France` package. For a different model you could achieve the same result by following the [offline environment](offline-environment) example to get local copies of the required packages.
+
 - Download the OpenFisca-France [installation files](https://github.com/openfisca/openfisca-france-offline/archive/master.zip)
-- Extract the content of this archive in a directory.
-- Go to that directory, then to the `windows` subdirectory. If you installed Python in 32 bits, **right-click** on `32-bits`. If you installed Python in 64 bits, **right-click** on the `64-bits` subdirectory. Choose "Git Bash Here"
+- Extract the content of this archive into a directory.
+- Go to that directory and then to the `windows` subdirectory. If you installed Python in 32 bits, **right-click** on `32-bits`. If you installed Python in 64 bits, **right-click** on the `64-bits` subdirectory. Choose "Git Bash Here"
 - Run the command `pip install *`
 
-To check that everything worked correctly, type in Git Bash:
+To check that everything works correctly, run the following command in Git Bash:
 
 ```sh
 python -c "from openfisca_france import CountryTaxBenefitSystem; CountryTaxBenefitSystem()"
@@ -56,7 +58,7 @@ No error message should appear. Congrats, you just installed OpenFisca-France!
 
 ## 4. Install atom
 
-Atom is a modern text editor that doesn't require administrator priviledges to be installed. It will allow you to edit Python files with syntaxing coloring.
+Atom is a modern text editor that doesn't require administrator privileges to be installed. It will allow you to edit Python files with syntaxing colouring.
 
 - Download atom from [https://atom.io/](https://atom.io/)