diff --git a/README.md b/README.md
index 2a49a39e..b94ec7b3 100644
--- a/README.md
+++ b/README.md
@@ -2385,7 +2385,8 @@ Notes:
       * Valid keys:
         - **`format`**: [string='ASCII'] [ASCII,CSV] Format for the position file.
         - **`only_smd`**: [boolean=true] Only include the surface mount components.
-        - **`output`**: [string='%f-%i%I%v.%x'] Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv'). Affected by global options.
+        - **`output`**: [string='%f-%i%I%v.%x'] Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv').
+                        Important: when using separate files you must use `%i` to differentiate them. Affected by global options.
         - **`separate_files_for_front_and_back`**: [boolean=true] Generate two separated files, one for the top and another for the bottom.
         - **`units`**: [string='millimeters'] [millimeters,inches,mils] Units used for the positions. Affected by global options.
         - `bottom_negative_x`: [boolean=false] Use negative X coordinates for footprints on bottom layer.
diff --git a/docs/samples/generic_plot.kibot.yaml b/docs/samples/generic_plot.kibot.yaml
index 8d5d87bf..dbe7723b 100644
--- a/docs/samples/generic_plot.kibot.yaml
+++ b/docs/samples/generic_plot.kibot.yaml
@@ -1334,7 +1334,8 @@ outputs:
       include_virtual: false
       # [boolean=true] Only include the surface mount components
       only_smd: true
-      # [string='%f-%i%I%v.%x'] Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv'). Affected by global options
+      # [string='%f-%i%I%v.%x'] Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv').
+      # Important: when using separate files you must use `%i` to differentiate them. Affected by global options
       output: '%f-%i%I%v.%x'
       # [boolean=true] Generate two separated files, one for the top and another for the bottom
       separate_files_for_front_and_back: true
diff --git a/kibot/out_position.py b/kibot/out_position.py
index 3de348e9..f74f192b 100644
--- a/kibot/out_position.py
+++ b/kibot/out_position.py
@@ -66,7 +66,8 @@ class PositionOptions(VariantOptions):
             self.only_smd = True
             """ *Only include the surface mount components """
             self.output = GS.def_global_output
-            """ *Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv') """
+            """ *Output file name (%i='top_pos'|'bottom_pos'|'both_pos', %x='pos'|'csv').
+                Important: when using separate files you must use `%i` to differentiate them """
             self.units = 'millimeters'
             """ *[millimeters,inches,mils] Units used for the positions. Affected by global options """
             self.columns = PosColumns