add rationals page to the docs

docs/index.markdown

@@ -4,10 +4,12 @@ title: About Vault Maven Plugin
 nav_order: 1
 ---
 
-# No need to store your credentials locally anymore 
+# Maven comes to the rescue to manage your app credentials
 {: .fs-9 }
 
-The Vault Maven Plugin allows you to fetch credentials from HashiCorp Vault and inject them as environment variables. Allowing your program to use them directly, instead of managing the credentials locally on each environment (developpers' local, CI pipelines, or production environment)
+The Vault Maven Plugin allows you to fetch credentials from HashiCorp Vault and make it available to your application.  
+Leveraging maven's portability and its plugin based system,  
+it allows easy integration with your app and can be used as a single tool for all environments (developers’ local, CI pipelines, or production K8s environment).
 {: .fs-6 .fw-300 }
 
 [![Quick Start](https://img.shields.io/badge/-Quick%20Start%20%F0%9F%9A%80-blue?style=for-the-badge&logo=rocket)](/vault-maven-plugin/usage.html)
@@ -30,43 +32,12 @@ As a result your application can use its secrets directly from those env variabl
 The only thing to manage is the credentials to login into Vault, and the list of secret keys you need :massage_man:.  
 * * *
 ## Why and When to use it ?
-Today, most of the software applications are communicating with other applications, using some sort of credentials for identifying themselves before establishing a secure communication,    
-or some encryption keys for securing the communication itself.  
-[Hashicorp Vault](https://www.vaultproject.io/) allows us to securely store those secrets, and share them with necessary counterparts.
-Those counterparts may be developers who want to run the application on their local environments, or the application's different execution environments (Test, Production, CI ect...)  
-
-Organisations that has a Hashicorp Vault, in general, are already using a cloud based architecture.    
-Hence, already have some ways for the application's credentials to be fetched automatically from Vault, instead of storing them locally on each environment separately.  
-Ex: Orchestrated Container environments like Kubernetes,  
-or CI tools like Jenkins have a Vault plugin to do so.  
-
-{: .warning }
-All those plugins/tools, all require you to declare your secrets on their own configuration file, causing duplication among different config files.
-
-{: .important }
-By using this plugin to fetch your secrets, you can unify all your configuration and secrets declaration in a single file, the pom.xml.  
-So everything, except the credentials to vault, can be stored on version control.  
-And if you use Github PAT authentication, even that can be on version control!  
-
-{: .warning }
-The idea behind using those plugins/tools, like jenkins Vault plugin or the Vault Agent that is used to save your secrets on K8s, is to fetch the credentials in advance, so that they are available right away at the start time of your application, making it to boot faster.
-
-{: .important }
-But there are some cases, for example batch applications, where we may prefer to tradeoff for the simplicity of configuration over the speed of startup :massage_man:.  
-Just keep in mind that fetching the secrets in time of execution has an implication of I/O, network and additional time of startup.  
-
-But still If you are sensible to the boot time of your application, lets say you have a web scaling app running on K8s,  
-You can still use this plugin, still with a single definition of your secrets in the pom.xml, to create your secret.yaml for K8s at its deployment time instead of the boot time. :wink:   
-
-
-But it may also be the case that : 
-* Your enterprise's IT infrastructure does not have such tools yet,  
-* It may be in a transition phase, or maybe some legacy applications that are not compatible with such tools.  
-* For some reason even if you have such tools, the Vault plugins are not available.   
-* **Such tools are not available on developers' local environments,**  
-where lots of enterprises still provide Windows PCs without a Docker or K8s.
-
-This plugin aims to help all those cases :santa:.
+An alternative to the [vault agent](https://developer.hashicorp.com/vault/docs/agent-and-proxy/agent) and framework specific tools like [spring-cloud-vault](https://cloud.spring.io/spring-cloud-vault/reference/html/), the project aims to answer use cases that  
+require the separation of the configuration from the component containing the business logic,    
+and require the portability and flexibility of the component managing the secrets,  
+while keeping the necessary configuration for all that as simple as possible (a single pom.xml file).  
+
+For more details, have a look at the [rationals](rationals.markdown) behind the project.
 
 * * *
 ## Example use cases

docs/rationals.markdown

@@ -0,0 +1,74 @@
+---
+layout: page
+title: The rationals behind it
+nav_order: 2
+---
+
+## Why and When to use it ?
+Today, most of the software applications are communicating with other applications, using some sort of credentials for identifying themselves before establishing a secure communication,    
+or some encryption keys for securing the communication itself.  
+[Hashicorp Vault](https://www.vaultproject.io/) allows us to securely store those secrets, and share them with necessary counterparts.
+Those counterparts may be developers who want to run the application on their local environments, or the application's different execution environments (Test, Production, CI/CD ect...)
+
+Organisations that has a Hashicorp Vault, in general, are already using a cloud based architecture.    
+Hence, already have some ways for the application's credentials to be fetched automatically from Vault, instead of storing them locally on each environment separately.  
+Ex: The most popular way for an app running on Orchestrated Container environments like Kubernetes is the [vault agent sidecar](https://www.hashicorp.com/blog/refresh-secrets-for-kubernetes-applications-with-vault-agent).    
+CI tools like Jenkins have a Vault plugin to fetch the secrets from Vault server.  
+Some java frameworks provide solutions so that your application can fetch secrets from vault directly, like [spring-cloud-vault](https://cloud.spring.io/spring-cloud-vault/reference/html/) or the Quarkus [vault-extension](https://docs.quarkiverse.io/quarkus-vault/dev/index.html).
+
+All those plugins/tools, have advantages and disadvantages, making each of the solutions ideal for specific use cases. The maven-vault plugin has its special usage as well.
+
+{: .important }
+Its biggest differences are: the simple usage (single config file for all environments, pom.xml), portability and flexibility leveraging maven's pure java platform and plugin based system. 
+
+---
+
+## Comparing the alternatives
+
+### 1. Configuration
+First of all the other alternatives require you to declare your secrets on their own configuration file, causing duplication among different config files.
+For example the vault agent has a specific configuration file. Spring cloud asks you to change lots of thins in your code base to use it.  
+both solutions require a new skill and knowledge to use it.
+
+By using the maven plugin to fetch your secrets, you can unify all your configuration and secrets declaration in a single file, the pom.xml.  
+No need to learn a new tool. :massage:
+
+### 2. Portability
+Environment specific tools, like vault agent for kubernetes or plugins for the CI tools, have their advantage in being optimised for that environment. But forces us to maintain multiple configs for multiple environments. Which makes the configuration overhead even worse.  
+It may also be the case that :
+* Your enterprise's IT infrastructure does not have such tools yet (no containers, no CI tools with plugins),
+* It may be in a transition phase, or maybe some legacy applications that are not compatible with such tools.
+* **Such tools are not available on developers' local environments,**  
+  where lots of enterprises still provide Windows PCs without a Docker or K8s. 
+
+Maven, hence the maven plugin, can be used wherever a JDK is available.  
+
+Also, the solutions provided by development frameworks like Spring cloud or Quarkus keeps the portability of the java environment, but asks you to change a lot your codebase, and they are framework specific.  
+Plus, according to the 12-factor app [requirements](https://www.hashicorp.com/blog/twelve-factor-applications-with-consul), there should be a clear separation between the configuration and the business logic of the application,
+which is clearly not the case when you embed in your application jar the management of your config and secrets.
+
+This plugin aims to help all those cases. :santa:
+
+---
+
+## Big picture
+
+|                                                                        | portability | fast execution | less configuration overhead | 12 factor compatibility |
+|------------------------------------------------------------------------|:-----------:|:--------------:|:---------------------------:|:-----------------------:|
+| vault agent                                                            |             |       ✅        |                             |                         |
+| spring-cloud-vault                                                     |      ✅      |       ✅        |                             |                         |
+| vaul-maven-plugin                                                      |      ✅      |                |              ✅              |            ✅            |
+| **[maven deamon](https://github.com/apache/maven-mvnd)** (coming soon) |      ✅      |       ✅        |              ✅              |            ✅            |
+
+### Special cases 
+
+{: .warning }
+The idea behind using plugins/tools optimised for specific environments, like jenkins Vault plugin or the Vault Agent on K8s, is to make your app boot faster.  
+Maven before running the plugin to fetch the secrets, and run your application, does lots of things. This of course has its overhead in terms of execution time and memory footprint.
+
+But there are some cases, for example batch applications, where we may prefer to tradeoff for the simplicity of configuration over the speed of startup. ⚖️
+
+Another sweet spot for the maven plugin is when you do not use the [dynamic secrets](https://www.hashicorp.com/blog/why-we-need-dynamic-secrets) or you do not modify your secrets on the [kv engine]() very often.
+If you are sensible to the boot time of your application, lets say you have a web scaling app running on K8s. 
+Keep in mind that fetching the secrets in time of execution has an implication of I/O, network and additional time of startup.
+You can use this plugin to create your secret.yaml for K8s at its deployment time instead of the boot time. :wink:

docs/usage.markdown

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: How to use it
-nav_order: 2
+nav_order: 3
 ---
 
 ## How to configure it

docs/use-cases/index.markdown

@@ -1,6 +1,6 @@
 ---
 layout: default
 title: Practical use cases
-nav_order: 3
+nav_order: 4
 has_children: true
 ---