docs(gh-page): update

streamthoughts · Oct 16, 2023 · 3c3a742 · 3c3a742
1 parent a0da3a9
commit 3c3a742
Show file tree

Hide file tree

Showing 6 changed files with 126 additions and 124 deletions.
diff --git a/README.adoc b/README.adoc
@@ -17,13 +17,12 @@ See: https://streamthoughts.github.io/jikkou/[official documentation]
 
 == Introduction
 
-**https://github.com/streamthoughts/jikkou[Jikkou]** (jikkō / 実行) is an open-source tool designed to provide an efficient and easy way to
-manage, automate, and provision resource configurations for Kafka, Schema Registry, etc.
+**https://github.com/streamthoughts/jikkou[Jikkou]** (jikkō / 実行) is an open-source tool built to provide an efficient
+and easy way to manage, automate, and provision resources on your event-stream platform.
 
-Developed by Kafka ❤️, Jikkou aims to streamline daily operations on https://kafka.apache.org/documentation/[Apache Kafka],
-ensuring that platform governance is no longer a boring and tedious task for both **Developers** and **Administrators**.
+Developed by Kafka ❤️, Jikkou aims to streamline daily operations on https://kafka.apache.org/documentation/[Apache Kafka], ensuring that platform governance is no longer a boring and tedious task for both **Developers** and **Administrators**.
 
-Jikkou enables a declarative management approach of **Topics**, **ACLs**, **Quotas**, **Schemas** and even more with the use of YAML files called **_Resource Definitions_**.
+Jikkou enables a declarative management approach of **Topics**, **ACLs**, **Quotas**, **Schemas**, **Connectors** and even more with the use of YAML files called **_Resource Definitions_**.
 
 Taking inspiration from `kubectl` and Kubernetes resource definition files, Jikkou offers an intuitive and user-friendly approach to configuration management.
 
@@ -35,60 +34,65 @@ See https://medium.com/@fhussonnois/why-is-managing-kafka-topics-still-such-a-pa
 
 == Installation
 
-The latest stable release of jikkou (x86) for Linux, and macOS can be downloaded from  https://github.com/streamthoughts/jikkou/releases/latest[GitHub Releases]
+The latest stable release of jikkou (x86) for Linux, and macOS can be retrieved via https://sdkman.io/[SDKMan]:
+
+```bash
+sdk install jikkou
+```
+
+Alternatively, the latest stable release of jikkou (x86) for Linux, and macOS can be downloaded from  https://github.com/streamthoughts/jikkou/releases/latest[GitHub Releases]
 
 Below are the convenience links for the base downloads of Jikkou.
 
 [%header,format=csv]
 |===
 Platform,Link
-Linux, ⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-linux-x86_64.zip[download (jikkou-0.29.0-linux-x86_64.zip)]
-macOS,⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-osx-x86_64.zip[download (jikkou-0.29.0-osx-x86_64.zip)]
+Linux, ⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-linux-x86_64.zip[download (jikkou-0.30.0-linux-x86_64.zip)]
+macOS,⬇️ https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-osx-x86_64.zip[download (jikkou-0.30.0-osx-x86_64.zip)]
 |===
 
-Alternatively, jikkou is also available:
-
-* As a fatJar available from https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.29.0/[Maven Central]
-* As a Docker Image available from https://hub.docker.com/r/streamthoughts/jikkou[Docker Hub].
-
-Download the jikkou binary from the https://github.com/streamthoughts/jikkou/releases[releases page], uncompress
-and copy to the desired location.
+Download the jikkou binary from the https://github.com/streamthoughts/jikkou/releases[releases page], uncompress and copy to the desired location.
 
-[source, bash]
+[source,bash]
 ----
 # Download the latest stable release
-wget https://github.com/streamthoughts/jikkou/releases/download/v0.29.0/jikkou-0.29.0-linux-x86_64.zip
+wget https://github.com/streamthoughts/jikkou/releases/download/v0.30.0/jikkou-0.30.0-linux-x86_64.zip
 
 # Uncompress
-unzip jikkou-0.29.0-linux-x86_64.zip
+unzip jikkou-0.30.0-linux-x86_64.zip
 
 # Copy to the desired location
-cp jikkou-0.29.0-linux-x86_64/bin/jikkou $HOME/.local/bin
+cp jikkou-0.30.0-linux-x86_64/bin/jikkou $HOME/.local/bin
 ----
 
-It is recommended to install the bash/zsh completion script `jikkou_completion`:
+Finally, Jikkou is can also be retrieved :
+
+* As a **fatJar** from https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.30.0/[Maven Central]
+* As a **Docker Image** from https://hub.docker.com/r/streamthoughts/jikkou[Docker Hub].
+
+Note, it is recommended to install the bash/zsh completion script `jikkou_completion`:
 
-[source, bash]
+[source,bash]
 ----
 wget https://raw.githubusercontent.com/streamthoughts/jikkou/main/jikkou_completion . jikkou_completion
 ----
 
 or alternatively, run the following command for generation the completion script.
 
-[source, bash]
+[source,bash]
 ----
 source <(jikkou generate-completion)
 ----
 
-WARNING: If you are using macOS you may need to remove the quarantine attribute from the bits before you can use them
-         To do this, run the following: `sudo xattr -r -d com.apple.quarantine path/to/jikkou/folder/`
+WARNING: If you are using macOS you may need to remove the quarantine attribute from the bits before you can use them To do this, run the following: `sudo xattr -r -d com.apple.quarantine path/to/jikkou/folder/`
 
 == Overview
 
 Here is an example of how to create and manage a _Kafka topic_ using Jikkou:
 
 * Create a resource file _kafka-topics.yaml_:
 kafka-topics.yaml:::
+
 [source,yaml]
 ----
 # file:./kafka-topics.yaml
@@ -107,19 +111,21 @@ spec:
 
 * Then run the following command:
 
-[source, bash]
+[source,bash]
 ----
 $ jikkou apply --files ./kafka-topics.yaml
 ----
 
 Jikkou will then take care of computing and applying the necessary changes directly to your cluster.
 
 _(output)_:
+
 [source]
 ----
 TASK [CREATE] Create a new topic my-first-topic-with-jikkou (partitions=12, replicas=3) - CHANGED **********************
 ----
-[source, json]
+
+[source,json]
 ----
 {
   "changed" : true,
@@ -146,6 +152,7 @@ TASK [CREATE] Create a new topic my-first-topic-with-jikkou (partitions=12, repl
   "status" : "CHANGED"
 }
 ----
+
 [source]
 ----
 EXECUTION in 2s 661ms (DRY_RUN)

diff --git a/docs/content/en/about/_index.md b/docs/content/en/about/_index.md
diff --git a/docs/content/en/about/featured-background.jpg b/docs/content/en/about/featured-background.jpg
diff --git a/docs/content/en/docs/Install/_index.md b/docs/content/en/docs/Install/_index.md
@@ -1,32 +1,43 @@
 ---
 title: "Install Jikkou"
 linkTitle: "Install"
-weight: 1
+weight: 2
 description: >
   This guide shows how to install the Jikkou CLI.
+menu:
+  main:
+    weight: 20
 ---
 
 {{% pageinfo %}}
 Jikkou can be installed either from source, or from releases.
 {{% /pageinfo %}}
 
+## From SDKMan! (recommanded)
+
+The latest stable release of jikkou (x86) for Linux, and macOS can be retrieved via https://sdkman.io/[SDKMan]:
+
+```bash
+sdk install jikkou
+```
+
 ## From The Jikkou Project
 
 ### Releases
 
 Every [`release`](https://github.com/streamthoughts/jikkou/releases) released versions of Jikkou is available:
 
 * As a zip/tar.gz package from [GitHub Releases](https://github.com/streamthoughts/jikkou/releases) (for Linux, MacOS)
-* As a fatJar available from [Maven Central](https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.26.0/)
+* As a fatJar available from [Maven Central](https://repo.maven.apache.org/maven2/io/streamthoughts/jikkou/0.30.0/)
 * As a docker image available from [Docker Hub](https://hub.docker.com/r/streamthoughts/jikkou).
 
 These are the official ways to get Jikkou releases that you manually downloaded and installed.
 
 #### Install From Release distribution
 
 1. Download your desired [version](https://github.com/streamthoughts/jikkou/releases)
-2. Unpack it (`unzip jikkou-0.26.0-linux-x86_64.zip`)
-3. Move the unpacked directory to the desired destination (`mv jikkou-0.26.0-linux-x86_64 /opt/jikkou`)
+2. Unpack it (`unzip jikkou-0.30.0-linux-x86_64.zip`)
+3. Move the unpacked directory to the desired destination (`mv jikkou-0.30.0-linux-x86_64 /opt/jikkou`)
 4. Add the executable to your PATH (`export PATH=$PATH:/opt/jikkou/bin`)
 
 From there, you should be able to run the client: `jikkou help`.

diff --git a/docs/content/en/docs/Overview/_index.md b/docs/content/en/docs/Overview/_index.md
@@ -0,0 +1,76 @@
+---
+title: "Overview"
+linkTitle: "Overview"
+description: "What is Jikkou ?"
+weight: 1
+menu:
+  main:
+    weight: 10
+ui.breadcrumb_disable: false
+---
+
+{{% pageinfo %}}
+Welcome to the Jikkou documentation! Jikkou, means “execution (e.g. of a plan) or actual state (of things)” in Japanese.
+{{% /pageinfo %}}
+
+## What is Jikkou ?
+
+Jikkou is a lightweight open-source tool designed to provide an efficient and easy way to manage, automate and provision
+resources on **Event-Driven Data Mesh platforms** (or, more simply, on any **Apache Kafka Infrastructures**).
+
+## How does Jikkou work ?
+
+Jikkou adopts a stateless approach and thus does not store any state internally. Instead, it leverages your platforms 
+or services as the source of truth. This design allows you to seamlessly integrate Jikkou with other solutions 
+(such as Ansible, Terraform, etc.) or use it on an ad hoc basis for specific needs, making it incredibly flexible and versatile
+
+## Why Jikkou ? The Story Behind Jikkou.
+
+Jikkou was originally created as a side project to help development teams quickly recreate topics on Apache Kafka
+clusters used for testing purposes (the project was called _Kafka Specs_). At the time, the aim was to ensure
+that environments were always clean and ready to run integration tests.
+
+But over time, new features were added, and so Jikkou was born with the aim to streamline day-to-day operations
+on Apache Kafka, ensuring that platform governance is no longer a tedious and boring task for both developers and
+administrators.
+
+Today, Jikkou is used in production on several projects, providing efficient management of Kafka resources through
+a GitOps approach. The project continues to evolve as an open-source project, as the solutions that have
+appeared over time in the Kafka ecosystem do not meet the needs of Kafka developers and administrators as well.
+In fact, existing solutions are either designed to work only with Kubernetes, or rely on dedicated services to manage
+the state of the solution.
+
+Now, we sincerely believe that Jikkou can play a role in bootstrapping a _self-service platform_ for a Data Mesh 
+organization, by unifying the way to manage the various assets required to create and manage a Data Product 
+exposed through Apache Kafka.
+
+## Is Jikkou for me ?
+
+Jikkou can be implemented regardless of the size of your team or data platform.
+
+### Small Development Team
+
+Jikkou is particularly useful for small development teams looking to quickly automate the creation and
+maintenance of their topics without having to implement a complex solution that requires learning a new technology
+or language.
+
+### Centralized Infrastructure (DevOps) Team
+
+Jikkou can be very effective in larger contexts, where the configuration of your Kafka Topics, ACLs, and Quotas
+for all your data platform is managed by a single and centralized devops team.
+
+### Decentralized Data Product Teams
+
+In an organization adopting Data Mesh principles, Jikkou can be leveraged in a decentralized way by each of your
+Data Teams to manage all the assets (e.g. Topics, ACLs, Schemas, Connectors, etc.) necessary to expose and manage
+their Data Products.
+
+## Can I Use Jikkou with my Apache Kafka vendor ?
+
+Jikkou can be used any Apache Kafka infrastructures, including:
+
+* [Apache Kafka](https://kafka.apache.org/)
+* [Aiven](https://aiven.io/kafka)
+* [Amazon MSK](https://aws.amazon.com/fr/msk/)
+* [Confluent Cloud](https://www.confluent.io/confluent-cloud/)
+* [Redpanda](https://redpanda.com/)
diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md
@@ -2,26 +2,12 @@
 ---
 title: "Documentation"
 linkTitle: "Documentation"
-weight: 20
+weight: 10
 menu:
   main:
-    weight: 20
+    weight: 30
 ---
 
-## Welcome to Jikkou
-
-Welcome to the Jikkou documentation. Jikkou is the tool to automate the management of the configurations that live on your Apache Kafka clusters.
-This guide shows you how to get started managing configurations for Topics, ACLS, Quotas, and more in the simplest and most seamless way possible.
-
-## Is Jikkou for me ?
-
-Jikkou is particularly useful for small development teams that want to quickly automate the creation and updating of their topics without having to implement complex solutions.
-But, it can be also very effective in larger contexts, where the configuration of your topics for all your projects are managed by a single centralized administration team.
-
-In addition, it is built on top of the Kafka's [Java AdminClient](https://kafka.apache.org/30/javadoc/org/apache/kafka/clients/admin/Admin.html). 
-Thus, it works out-of-the-box with most the Apache Kafka distributions and cloud provider managed services (e.g., [Aiven](https://aiven.io/), [Confluent Cloud](https://confluent.cloud/), etc).
-However, you may find some limitations with some managed services for Apache Kafka depending on which APIs are allowed to be used. Indeed, some providers limit for example some config properties to be overloaded or use own ACL management mechanisms.
-