Improve documentation

Author: AndreuCodina

README.md

@@ -18,15 +18,15 @@ docker compose --file docker-compose-dev.yaml down --volumes
 
 # Reasonings
 
-## .env files
+## Settings and .env files
 
-**Key points:**
+Each backend must be deployed to several environments (development, staging, production...), but each company uses different environments (from one to any number), so the backend is the only one that knows the number of environments and their names.
+Then, each environment has its own settings (e.g., the logging level or URL of an external service may vary between environments).
 
-- We store settings in .env files.
-- There's a .env.{environment} file for each environment (Local, Development, Staging, Production).
-- There's a .env file for common settings.
-- If a setting is in both .env and .env.{environment}, the one in .env.{environment} takes precedence.
+So, we'll use this rules to store settings:
+- Store settings in `.env` files.
+- A `.env` file for common settings.
+- A `.env.{environment}` file for each environment.
+- If a setting is in both `.env` and `.env.{environment}`, the one in `.env.{environment}` takes precedence.
 
-The typical is to save .env files in the root of the project, but due to some popular tools and libraries (Jupyter, FastAPI, Docker Compose...) load the file `.env` automatically (and an application has its own order, such as giving priority to the current environment, environment variables or a secret store), then we need to store them in another location (in this case, in the "api" folder) and give `ApplicationSettings` the path to the files.
-
-Note: Renaming `.env` to `.env.Common` in the root isn't better because if your notebook isn't in the root, you have to specify the path in `ApplicationSettings` anyway, and `Common` can be confusing because it's not an environment.
+Regarding the location of those files, the typical is to save `.env` files in the root of the project, but due to some popular tools and packages (Jupyter, FastAPI, Docker Compose...) load automatically and exclusively the file `.env`, ignoring the environments and the priority order defined by the backend (e.g., `.env.{environment}` has priority over `.env` because it's the current environment), then we need to store the `.env` files in another location (in this case, in the `api` folder) and give the backend the responsibility of loading them, taking into account the environment name.