docs: rework basic documentation

Author: kpetremann

content/_index.md

@@ -1,5 +1,6 @@
 ---
 layout: hextra-home
+description: Developer-first infrastructure automation and configuration — no DSL, just real code. Easy to use SDK. No lock-in.
 ---
 {{< hextra/hero-badge >}}
   <div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
@@ -8,7 +9,7 @@ layout: hextra-home
 
 <div class="hx:mt-6 hx:mb-6">
 {{< hextra/hero-headline >}}
-  Developer-first<br/>infrastructure automation.
+  Developer-first <br/>infrastructure automation.
 {{< /hextra/hero-headline >}}
 </div>
 

content/docs/configuration.md

@@ -7,20 +7,29 @@ toc: false
 {{< tabs items="Manager,Agent" >}}
   {{< tab >}}
 
-**Development configuration**
+**Test configuration**
+
+This minimal configuration can be used to ease testing in lab.
+
+Not recommenced for production.
 
 ```yaml {filename="/etc/jackadi/manager.yaml"}
-mtls: false
-auto-accept-agent: true
+mtls: false  # in developement, mTLS authentication can be skipped
+auto-accept-agent: true  # avoids having to accept agents manually
 ```
 
 **Minimal recommended configuration for production**
 
 ```yaml {filename="/etc/jackadi/manager.yaml"}
-address: "0.0.0.0"  # choose the listening address carefully
+# should listen only on the network you want to serve
+address: "0.0.0.0"
 
+# auto acceptation should be disabled,
+# unless you have a strong pki management
 auto-accept-agent: false
 
+# mTLS is critical for production to both
+# authenticate and encrypt communication
 mtls: true
 mtls-key: "/etc/jackadi/certs/manager.key"
 mtls-cert: "/etc/jackadi/certs/manager.crt"
@@ -30,18 +39,20 @@ mtls-agent-ca-cert: "/etc/jackadi/certs/ca.crt"
 
   {{< tab >}}
 
-**Development configuration**
+**Test configuration**
 
 ```yaml {filename="/etc/jackadi/agent.yaml"}
 manager-address: "192.0.2.1"
+mtls: false
 ```
 
 **Minimal recommended configuration for production**
 
 ```yaml {filename="/etc/jackadi/agent.yaml"}
 manager-address: "192.0.2.1"
 
-# Security settings (mTLS)
+# mTLS is critical for production to both
+# authenticate and encrypt communication
 mtls: true
 mtls-key: "/etc/jackadi/certs/agent.key"
 mtls-cert: "/etc/jackadi/certs/agent.crt"

content/docs/installation.md

@@ -5,7 +5,7 @@ weight: 2
 
 ## Linux packages (recommended)
 
-1. Download and install Jackadi. `.deb` and `.rpm` files are available in the [GitHub releases](https://github.com/jackadi-io/jackadi/releases).
+1. Download and install Jackadi. Installation files (`.deb` and `.rpm`) are available in the [GitHub releases](https://github.com/jackadi-io/jackadi/releases).
 2. Edit the configuration (see [Configuration](/docs/configuration) page).
 3. Start the service and ensure it is running:
 ```sh
@@ -21,7 +21,7 @@ systemctl status jackadi-agent
 ## Manual installation
 
 {{< callout type="warning" >}}
-You will need to manually create some directories to make it work (see [File Structure]({{<ref "#file-structure" >}}) section).
+To install Jackadi manually, you will need to manually create all the directories to make it work (see [File Structure]({{<ref "#file-structure" >}}) section to get the list of directories to create).
 {{< /callout >}}
 
 {{< callout type="tips" >}}
@@ -46,6 +46,8 @@ make build
 
 ## File structure
 
+Once everything is installed, you should have the following directory layout:
+
 | Manager | Agent |
 |---------|-------|
 | {{< filetree/container >}}

content/docs/introduction.md

@@ -17,7 +17,7 @@ Key principles:
 
 ## Features
 
-| Feature | Description |
+| | Description |
 |---------|-------------|
 | **Distributed Task Execution** | Execute tasks across multiple agents from a central manager. |
 | **Plugin System**              | Extend functionality through custom Go plugins. |
@@ -28,13 +28,11 @@ Key principles:
 
 ## Architecture
 
-In a nutshell:
-* Agents are connected to a manager via persistent bidirectional gRPC.
-* Simple plugin system:
-  * All tasks and specs collectors are pure Go functions.
-  * The plugin system is based on [hashicorp/go-plugin](https://github.com/hashicorp/go-plugin/).
-  * The SDK is simple and easy to use.
-* Tasks results are stored in a local [BadgerDB](https://github.com/hypermodeinc/badger).
+Agents are connected to a manager via persistent bidirectional gRPC connections.
+
+Jackadi features a simple plugin architecture where all tasks and specs collectors are implemented as pure Go functions. The plugin system is built on top of [hashicorp/go-plugin](https://github.com/hashicorp/go-plugin/), and is made intuitive using a simple and easy to use SDK.
+
+By default, all executed task are recorded in [BadgerDB](https://github.com/hypermodeinc/badger).
 
 ## Quick demo tour
 

hugo.yaml

@@ -35,7 +35,7 @@ markup:
 menu:
   main:
     - name: Documentation
-      pageRef: /docs/introduction
+      pageRef: /docs
       weight: 1
     - name: Search
       weight: 2