docs: Adjust physical layouts page

1 files changed, 23 insertions, 55 deletions

diff --git a/docs/docs/development/hardware-integration/physical-layouts.md b/docs/docs/development/hardware-integration/physical-layouts.md
index 8f3c20ddc8..e35ca78260 100644
--- a/docs/docs/development/hardware-integration/physical-layouts.md
+++ b/docs/docs/development/hardware-integration/physical-layouts.md
@@ -66,8 +66,12 @@ A key description has the shape `<&key_physical_attrs w h x y r rx ry>` with the
 | Rotation X | int      | Rotation origin X position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
 | Rotation Y | int      | Rotation origin Y position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
 
-:::tip
 You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation.
+
+:::tip
+
+We recommend the use of [this tool](https://zmk-physical-layout-converter.streamlit.app/) for writing a physical layout or converting one from a QMK JSON definition. If your keyboard already has a physical layout defined for the use with KLE, we recommend using [this other tool](https://nickcoutsos.github.io/keymap-layout-tools/) first to convert your existing layout into QMK JSON.
+
 :::
 
 ### Physical Layout with Keys Example
@@ -175,6 +179,12 @@ If necessary, you can also define multiple kscan instances.
 
 When switching between layouts using [ZMK Studio](../../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used.
 
+:::warning
+
+Keys whose positions can neither be inferred from the default layout nor have bindings in the position map cannot be assigned to.
+
+:::
+
 A position map looks something like this:
 
 ```dts
@@ -203,6 +213,12 @@ The position map should be marked as `complete` if all desired binding transfers
 
 See also the [configuration section on position maps](../../config/layout.md#physical-layout-position-map).
 
+:::tip
+
+We recommend the use of [this tool](https://zmk-layout-helper.netlify.app/), distinct from the previous two mentioned, for the purposes of writing a position map.
+
+:::
+
 #### Writing a position map
 
 Start by creating the parent node defining the position map:
@@ -295,7 +311,7 @@ If the left side with more keys was used as the reference layout, then the overa
 
 ```dts
 / {
-    keypad_lossless_position_map {
+    keypad_position_map1 {
         compatible = "zmk,physical-layout-position-map";
         complete;
 
@@ -328,7 +344,7 @@ If the right side with fewer keys were used as a reference instead, then the ove
 
 ```dts
 / {
-    keypad_lossy_position_map {
+    keypad_position_map2 {
         compatible = "zmk,physical-layout-position-map";
         complete;
 
@@ -355,7 +371,7 @@ If the right side with fewer keys were used as a reference instead, then the ove
 };
 ```
 
-The above example is "lossy" because (unlike the previous "lossless" example) if a user switches from the macropad layout to the numpad layout _and then_ switches from the numpad layout back to the macropad layout, the assignments to the keys present but not listed in the macropad's map are lost.
+There is functionally no difference between the two approaches, but the first approach is recommended.
 
 #### Example non-`complete` position map
 
@@ -365,7 +381,7 @@ A non-`complete` position map can be used to assign mappings to only these parti
 
 ```dts
 / {
-    keypad_lossy_position_map {
+    keypad_position_map3 {
         compatible = "zmk,physical-layout-position-map";
 
         macropad_map: macropad {
@@ -381,31 +397,11 @@ A non-`complete` position map can be used to assign mappings to only these parti
 };
 ```
 
-This is noticably simpler to write, and can be a useful way of saving flash space for memory-constrained devices. The above is a "lossy" mapping, though. While "lossless" non-`complete` mappings are possible, they can be counter-intuitive enough that it may be easier to write the full position map instead.
-
-For completeness, the equivalent "lossless" non-`complete` position map is shown below:
-
-```dts
-/ {
-    keypad_lossy_position_map {
-        compatible = "zmk,physical-layout-position-map";
-
-        macropad_map: macropad {
-            physical-layout = <&macropad_layout>;
-            positions = <7 11 15 19 16 17>;
-        };
-
-        numpad_map: numpad {
-            physical-layout = <&numpad_layout>;
-            positions = <7 19 14 18 15 17>;
-        };
-    };
-};
-```
+This is noticably simpler to write, and can be a useful way of saving flash space for memory-constrained devices.
 
 #### Additional example: corne
 
-The following is an example of a "lossless" position map which maps the 5-column and 6-column Corne keymap layouts. The 6 column layout is the reference layout.
+The following is an example of a position map which maps the 5-column and 6-column Corne keymap layouts. The 6 column layout is the reference layout.
 
 ```dts
     foostan_corne_lossless_position_map {
@@ -432,31 +428,3 @@ The following is an example of a "lossless" position map which maps the 5-column
         };
     };
 ```
-
-Meanwhile, the "lossy" version of the same position map with the 5 column version as reference looks like this:
-
-```dts
-    foostan_corne_lossy_position_map {
-        compatible = "zmk,physical-layout-position-map";
-
-        complete;
-
-        twelve_map: twelve {
-            physical-layout = <&foostan_corne_6col_layout>;
-            positions
-                = < 1  2  3  4  5  6  7  8  9 10>
-                , <13 14 15 16 17 18 19 20 21 22>
-                , <25 26 27 28 29 30 31 32 33 34>
-                , <      36 37 38 39 40 41      >;
-        };
-
-        ten_map: ten {
-            physical-layout = <&foostan_corne_5col_layout>;
-            positions
-                = < 0  1  2  3  4  5  6  7  8  9>
-                , <10 11 12 13 14 15 16 17 18 19>
-                , <20 21 22 23 24 25 26 27 28 29>
-                , <      30 31 32 33 34 35      >;
-        };
-    };
-```