Improve copywriting for Installation (#306)

source/installation/access-countrys-source-code.md

@@ -0,0 +1,21 @@
+# Access a country's source code
+
+This section provides instructions to run or modify the [source code](https://github.com/openfisca/country-template) of the `OpenFisca-Country-Template` package.
+
+These instructions should be able to be followed for any OpenFisca country package, just substitute the `OpenFisca-Country-Template` package with the relevant OpenFisca country package.
+
+OpenFisca runs with [Python](https://www.python.org/). Its source code is managed with the [Git](https://git-scm.com) version control software. The following steps call the [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation and a `git` command. To check their installation or install them, follow the [Installation requirements](installation-requirements.md) section.
+
+The `OpenFisca-Country-Template` installation instructions are in its `README` [Advanced installation](https://github.com/openfisca/country-template#b-advanced-installation-git-clone) section.
+
+> 💡 Other OpenFisca models have their own documentation. Check the existing repositories list on the [Available Packages](https://openfisca.org/en/packages/) section of the openfisca.org website.
+
+## Testing changes on "ready to use" situations
+
+Generally when making changes to legislation, there is a need to test the changes with a situation that works with the country's tax and benefit system.
+
+Sometimes, these situations can be quite complicated to model. Instead of rewriting them everytime, they can be packaged in different formats:
+
+* As [YAML tests](./../coding-the-legislation/writing_yaml_tests.md) when the expected output result should be registered.
+* As [JSON requests](./../openfisca-web-api/input-output-data.md#describing-the-situation) when the output isn't being tested. Refer to [these examples](https://github.com/openfisca/country-template/tree/main/openfisca_country_template/situation_examples) in the `OpenFisca-Country-Template` repository. These can be adapted as requests to be sent to the OpenFisca web API.
+* As [CSV or other data formats](./../simulate/run-simulation.md#data) when there is a large number of situations to save.

source/installation/call-existing-web-api.md

@@ -0,0 +1,13 @@
+# Call an existing web API
+
+The web API is made for online web applications. Before hosting your country web API, you can check if it already exists or use the demonstration of the `OpenFisca-Country-Template` web API hosted by OpenFisca community. It is available for testing and interacting with its web API endpoints through [this swagger interface](https://legislation.demo.openfisca.org/swagger). As with all OpenFisca country web APIs it does not require configuring or installing anything to access it.
+
+For further information on the possible requests, [this section of the documentation](./../openfisca-web-api/endpoints.md) describes OpenFisca web APIs endpoints.
+
+> 💡 Other OpenFisca models might have their own hosted web APIs. When looking for an already hosted web API of a specific country package, it is recommended to check the terms of use and contact the maintaining team.
+
+The `OpenFisca-Country-Template` demonstration API provides examples of the endpoints that are available with all OpenFisca packages. To develop an application that requires calculations specific to a country, that country's OpenFisca web API will be required to access the variables and calculations specific to that country.
+
+It is advised to host specific OpenFisca instances per application as changes to laws can often require application changes. This will give maintainers the ability to migrate the application to the latest version of a country package in their own timeframes.
+
+Read [Install a country web API](./install-country-web-api.md) for more information.

source/installation/index.md

@@ -1,23 +1,58 @@
-# <i icon-name="download"></i> Installation
+# <i icon-name="download"></i> Getting started
 
 ```{toctree}
 :hidden:
 
-howto-web-no-local-install
-howto_docker
+call-existing-web-api
+installation-requirements
+install-country-web-api
+install-country-package
+python-api-browser
+access-countrys-source-code
+install-with-docker
 offline-environment
 windows-no-admin
-test_situations
 ```
 
-As the OpenFisca community becomes larger, issues that only affect a small percentage of users arise.
+This section is a guide to the various methods of accessing or installing OpenFisca. Follow the guide below to establish what the use case is and get directed to the appropriate section(s).
 
-The purpose of this section is to bring together the clever solutions the community came up with and share them with all OpenFisca users.
+## 1) Identify the country package
 
-- [How to use OpenFisca on the web (no installation required on your computer)](./howto-web-no-local-install.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)
+The most common approach involves a specific country or jurisdiction package and so in this scenario it's important to identify if that package exists and then continue to step 2 _"Clarify use case"_.
+If the goal is contributing to OpenFisca directly (such as this documentation); have a look at the [Contribute](/contribute/index.md) section of this site and also the [OpenFisca Github repositories](https://github.com/openfisca/).
 
-> 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.
+## 2) Clarify use case
+
+With a specific country or jurisdiction package in mind; ask whether the use case requires [contributions to the rules](index.md#contributing-to-the-rules), or intends to just [utilise existing rules](index.md#utilising-existing-rules) (for example: run simulations).
+
+### Utilising existing rules
+
+If the goal is just to utilise existing rules (rather than contributing to the rules) then consider the following options.
+
+#### Web API
+
+Best for online web applications. The two options are:
+
+* If it exists, [call an existing web API](./call-existing-web-api.md) for your country (no installation necessarily), or
+* [Install a country web API](./install-country-web-api.md) to operate your own web API with no usage limitations (see also [Install with Docker](./install-with-docker.md)).
+
+#### Python API
+
+Suitable for "desktop" processing and running large simulations:
+
+* [Install a country package](./install-country-package.md) in a local environment (see also [Install with Docker](./install-with-docker.md)).
+* Alternatively, access the [Python API in the browser](./python-api-browser.md).
+
+### Contributing to the rules
+
+If the goal includes contributing to the rules of a country package:
+
+* When it already exists, [access a country's source code](./access-countrys-source-code.md).
+* Otherwise, [bootstrap a new country package](/coding-the-legislation/bootstrapping_a_new_country_package.md)
+
+## Edge cases
+
+Finally, some specific edge cases have been described by the OpenFisca community as follows:
+
+* Installing a specific country OpenFisca package in an [offline environment](./offline-environment.md).
+* Installing a specific country OpenFisca package on a [Windows machine without administrative rights](./windows-no-admin.md).

source/installation/install-country-package.md

@@ -0,0 +1,27 @@
+# Install a country package
+
+This section is a guide on how to install the `OpenFisca-Country-Template` [packaged library](https://pypi.org/project/OpenFisca-Country-Template/).
+
+These instructions should be able to be followed for any OpenFisca country package that has published their package on [https://pypi.org/](https://pypi.org/)
+
+It's the minimal installation required to run a country package without the intention of contributing to it. If the use case also requires contributing to the model, please follow the [access a country's source code](./access-countrys-source-code.md) section.
+
+## Install OpenFisca-Country-Template packaged library
+
+OpenFisca runs with [Python](https://www.python.org/). The following steps call [pip package installer](https://pypi.org/project/pip/) which requires a `Python` installation. To check its installation or install it, first check the [Installation requirements](installation-requirements.md).
+
+> When other Python projects exist in the intended environment, it is recommended to create a new virtual environment to avoid dependency conflicts. [Here is more information](https://github.com/openfisca/country-template#setting-up-a-virtual-environment-with-venv) from `OpenFisca-Country-Template` documentation.
+
+To install the latest OpenFisca-Country-Template [published revision](https://pypi.org/project/OpenFisca-Country-Template/#history), run the following command in the environment's terminal:
+
+```shell
+pip install OpenFisca-Country-Template
+```
+
+It should complete without any errors. To check the installed packages run the following command:
+
+```shell
+pip list
+```
+
+`OpenFisca-Country-Template` should be in the list indicating that it is installed and ready to run simulations.

source/installation/install-country-web-api.md

@@ -0,0 +1,13 @@
+# Install a country web API
+
+These instructions are for installing an OpenFisca country package in a local environment. The `OpenFisca-Country-Template` package is used as an example here and should be substituted for the specific country package relevant to the use case.
+
+## Run and call a local web API
+
+OpenFisca runs with [Python](https://www.python.org/). If it's not installed in the environment, check the [Installation requirements](installation-requirements.md#install-python) section.
+
+To run a local `OpenFisca-Country-Template` web API:
+
+1. Install the `OpenFisca-Country-Template` in the local environment as described by it's `README` [Install Instructions for Users and Contributors](https://github.com/openfisca/country-template#install-instructions-for-users-and-contributors) section,
+
+2. Serve the web API on your environment by running the one command described [here](https://github.com/openfisca/country-template#serve-this-country-package-with-the-openfisca-web-api).

source/installation/install-with-docker.md

@@ -0,0 +1,81 @@
+# Install with Docker
+
+Using Containers such as Docker to install OpenFisca is useful when a reproducible environment is important or the [Installation requirements](installation-requirements.md) process is either not desirable or not possible.
+
+A container platform such as [Docker](https://www.docker.com) sets up the required environment usually on a minimal image of a Unix operating system.
+In a container, exists an isolated environment with user rights to install OpenFisca. The following instructions are for Docker, you may also want to check out [Podman.](https://podman.io).
+
+> Install the free [Docker Community Edition](https://docs.docker.com/install/#supported-platforms) (also named `Docker Desktop`).
+>
+> - Follow default installation instructions (requires creation of a free Docker ID).
+> - Run installed Docker application (to activate docker daemon).
+>
+> On the Windows operating system, Windows 10 or higher is required to use Docker.
+
+## Install OpenFisca in a Docker container
+
+These instructions are for the [openfisca-country-template](https://github.com/openfisca/country-template) but should be able to be followed for any OpenFisca country package.
+The instructions create a directory named `my-openfisca` where any changes made are visible both on the local machine and in the Docker environment.
+
+1. Setup a working directory:  
+   + For these instructions create a new directory named `my-openfisca`.
+   + Open the system console (`cmd.exe` for Windows OS, a bash Terminal for Unix/Linux/Mac) and run:
+
+        ```sh
+        cd my-openfisca # Updated with the real path to your working directory
+        ```
+
+2. Build a container with the [appropriate Python version](installation-requirements.md#how-to-find-the-python-version-of-a-model), Git and console commands.
+   > Note that Git comes with the Python image.
+
+   + For Linux/Unix/Mac operating systems, run the following command (swapping `python:3.11` for the appropriate Python version):
+
+        ```sh
+        docker run --rm -it -v $PWD:/my-openfisca -w /my-openfisca python:3.11 bash
+        ```
+
+   + For Windows operating system, run the following command (swapping `python:3.11` for the appropriate Python version):
+
+        ```sh
+        docker run --rm -it -v %cd%:/my-openfisca -w /my-openfisca python:3.11 bash
+        ```
+
+3. Check the installed libraries with the `pip list` command.
+   This should result in the following list of packages:
+
+    ```sh
+     Package    Version
+     ---------- -------
+     pip        *.*.*   
+     setuptools *.*.* 
+     wheel      *.*.* 
+    ```
+
+4. Install the [openfisca-country-template](https://github.com/openfisca/country-template). The chosen approach depends on the use case, specifically if the intention is to contribute to the rules.
+
+   + To contribute to the `openfisca-country-template`, get its source code with:
+
+        ```sh
+        git clone https://github.com/openfisca/country-template.git
+        ```
+
+        _Note for other OpenFisca country packages change the git repository address as appropriate._
+
+        Then, install it with:
+
+        ```sh
+        cd country-template
+        make install
+        ```
+
+   + Alternatively to run the `openfisca-country-template` without modifying it, install it as a library with:
+
+        ```sh
+        pip install openfisca_country_template
+        ```
+
+        _Note for other OpenFisca country packages, check first if it is published on [https://pypi.org/](https://pypi.org/) and substitute `openfisca_country_template` for the appropriate package name._
+
+   In both cases, the installation should end without error, and the `pip list` response should contain `OpenFisca-Country-Template`.
+
+This should complete the installation of `openfisca-country-template`, any changes to the local `my-openfisca/` files will be reflected in the `my-openfisca/` files in Docker, and vice-versa.