From dd2e35345ffe71957173b2d4b0544a225d849798 Mon Sep 17 00:00:00 2001
From: ieQu1 <99872536+ieQu1@users.noreply.github.com>
Date: Fri, 23 Feb 2024 13:41:05 +0100
Subject: [PATCH] docs(ds): Apply remarks

---
 rel/i18n/emqx_ds_schema.hocon | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/rel/i18n/emqx_ds_schema.hocon b/rel/i18n/emqx_ds_schema.hocon
index 452d46258..746874620 100644
--- a/rel/i18n/emqx_ds_schema.hocon
+++ b/rel/i18n/emqx_ds_schema.hocon
@@ -13,7 +13,9 @@ builtin.desc:
 builtin_data_dir.label: "Database location"
 builtin_data_dir.desc:
   """~
-  File system directory where the database is located.~"""
+  File system directory where the database is located.
+
+  By default it is equal to `node.data_dir`.~"""
 
 builtin_n_shards.label: "Number of shards"
 builtin_n_shards.desc:
@@ -33,19 +35,32 @@ builtin_layout.desc:
   """~
   Storage layout is a method of arranging messages from various topics and clients on disc.
 
-  Depending on the type of workload and the topic structure, different types of strategies for storing the data can be employed to maximize efficency of the replay.~"""
+  Depending on the type of workload and the topic structure, different types of strategies for storing the data can be employed to maximize efficiency of reading messages from the durable storage.~"""
 
 layout_wildcard_optimized.label: "Wildcard-optimized storage layout"
 layout_wildcard_optimized.desc:
   """~
-  _Wildcard-optimized_ layout is designed to maximize the throughput of the wildcard subscriptions covering large numbers of topics.~"""
+  _Wildcard-optimized_ layout is designed to maximize the throughput of wildcard subscriptions covering large numbers of topics.
 
-wildcard_optimized_epoch_bits.label: "Epoch size"
+  For example, it can handle scenarios where a very large number of clients publish data to the topics containing their client ID, such as: `sensor/%device-version%/%clientid%/temperature`, `sensor/%device-version%/%clientid%/pressure`, etc.
+  This layout will automatically group such topics into a single stream, so a client subscribing to a topic filter containing wildcards (such as `sensor/+/+/temperature`) will be able to consume messages published by all devices as a single batch.
+
+  This layout is efficient for non-wildcard subscriptions as well.~"""
+
+wildcard_optimized_epoch_bits.label: "Epoch bits"
 wildcard_optimized_epoch_bits.desc:
   """~
   Wildcard-optimized layout partitions messages recorded at different times into "epochs".
-  Each epoch can be consumed by the subscribers as a batch.
-  Generally, larger epochs lead to higher throughput of subscribers, however currently they may increase latency.~"""
+  Reading messages from a single epoch can be done very efficiently, so larger epochs improve the throughput of subscribers, but may increase end-to-end latency
+
+  Time span covered by each epoch grows exponentially with the value of `epoch_bits`:
+
+  - `epoch_bits = 1`: epoch time = 1 millisecond
+  - `epoch_bits = 2`: 2 milliseconds
+  ...
+  - `epoch_bits = 10`: 1024 milliseconds
+  - `epoch_bits = 13`: ~8 seconds
+  ....~"""
 
 egress_max_items.label: "Max items"
 egress_max_items.desc: