diff --git a/docs/source/programming.rst b/docs/source/programming.rst
index 1f274bb0f..5e4d83523 100644
--- a/docs/source/programming.rst
+++ b/docs/source/programming.rst
@@ -342,16 +342,14 @@ See also :ref:`pointervars_programming`
 
 **LSB/MSB split word arrays:**
 For (u)word arrays, you can make the compiler layout the array in memory as two separate arrays,
-one with the LSBs and one with the MSBs of the word values. This is more efficient when storing
-and reading words from the array (the index can be used twice).
-Add the ``@split`` tag to the variable declaration to do this.
-In the assembly code, the array will be generated as two byte arrays namely ``name_lsb`` and ``name_msb``.
-Note that the maximum length of a split word array is 256! (regular word arrays are limited to 128 elements).
+one with the LSBs and one with the MSBs of the word values. This makes it more efficient to access
+values from the array (smaller and faster code). It also doubles the maximum size of the array from 128 words to 256 words!
+The ``@split`` tag should be added to the variable declaration to do this.
+In the assembly code, the array will then be generated as two byte arrays namely ``name_lsb`` and ``name_msb``.
 
 .. caution::
     Not all array operations are supported yet on "split word arrays".
-    The compiler may give an unpleasant error or crash when you hit such a case in your code.
-    If this happens simply revert to a regular word array and please report the issue,
+    If you get an error message, simply revert to a regular word array and please report the issue,
     so that more support can be added in the future where it is needed.
 
 
diff --git a/docs/source/syntaxreference.rst b/docs/source/syntaxreference.rst
index fe6782260..df77539c1 100644
--- a/docs/source/syntaxreference.rst
+++ b/docs/source/syntaxreference.rst
@@ -344,7 +344,7 @@ Tag         Effect
 @requirezp  force the variable into Zero page. If ZP is full, compilation will fail.
 @nozp       force the variable to normal system ram, never place it into zeropage.
 @shared     means the variable is shared with some assembly code and that it cannot be optimized away if not used elsewhere.
-@split      (only valid on (u)word arrays) Makes the array to be placed in memory as 2 separate byte arrays; one with the LSBs one with the MSBs of the word values. May improve performance.
+@split      (only valid on (u)word arrays) Makes the array to be placed in memory as 2 separate byte arrays; one with the LSBs one with the MSBs of the word values. Usually improves performance and code size.
 ==========  ======
 
 
diff --git a/docs/source/todo.rst b/docs/source/todo.rst
index 1dae37e6b..ede881340 100644
--- a/docs/source/todo.rst
+++ b/docs/source/todo.rst
@@ -1,8 +1,6 @@
 TODO
 ====
 
-docs: stress more that the @split for word arrays can provide significant code efficiency over normal linear word array
-
 optimizer bug, see "optimizing inlined functions must reference proper scopes" unittest (skipped for now)
 causes compiler error for virtual: just calling txt.cls() gives compile error undefined symbol clear_screen