diff --git a/docs/guide/form-fields/list.md b/docs/guide/form-fields/list.md
index b22c4d44c..85abb3cd3 100644
--- a/docs/guide/form-fields/list.md
+++ b/docs/guide/form-fields/list.md
@@ -99,8 +99,9 @@ class MyForm extends SharpForm
     function buildFormLayout(FormLayout $formLayout)
     {
         $this->addColumn(6, function (FormLayoutColumn $column) {
-             $column->withSingleField('pieces', function (FormLayoutColumn $listItem) {
-                  $listItem->withField('acquisition_date')
+             $column->withListField('pieces', function (FormLayoutColumn $listItem) {
+                  $listItem
+                      ->withField('acquisition_date')
                       ->withField('title')
                       ->withField('artist_id');
              });
diff --git a/docs/guide/upgrading/9.0.md b/docs/guide/upgrading/9.0.md
index d5e0b3ebf..0216ff54e 100644
--- a/docs/guide/upgrading/9.0.md
+++ b/docs/guide/upgrading/9.0.md
@@ -533,13 +533,43 @@ This is not a breaking change, in fact you can ignore this step entirely, but si
 
 ## Form and Show layout methods were renamed (old ones are deprecated)
 
-The `->withSingleField()` method was deprecated, in favor of:
-
-- `->withField(string $fieldKey)` for simple fields
-- `->withListField(string $fieldKey, Closure $subLayoutCallback)` for List fields, which requires a sub-layout handled by a callback.
+The `->withSingleField()` method was deprecated, in favor of `->withField(string $fieldKey)` for simple fields.
 
 The method `->withFields(string ...$fieldKeys)`, used for multiple fields layout, remains unchanged.
 
+## Form and Show list fields must now use `->withListField()` instead of  `->withSingleField()` in layout
+
+In 8.x:
+```php
+class MyForm extends SharpForm
+{
+    function buildFormLayout(FormLayout $formLayout)
+    {
+        $this->addColumn(6, function (FormLayoutColumn $column) {
+            $column->withSingleField(string $fieldKey, function (FormLayoutColumn $listItem) {
+                $listItem->withField('title');
+            });
+        });
+    }
+}
+```
+
+In 9.x:
+```php
+class MyForm extends SharpForm
+{
+    function buildFormLayout(FormLayout $formLayout)
+    {
+        $this->addColumn(6, function (FormLayoutColumn $column) {
+            // now `->withListField()`
+            $column->withListField(string $fieldKey, function (FormLayoutColumn $listItem) {
+                $listItem->withField('title');
+            });
+        });
+    }
+}
+```
+
 ## Form and Show Fields are now formatted even if you don’t transform them
 
 This shouldn’t cause any trouble, as this is a fix, but it could break unorthodox code: field formatters (which are used to format the field value for the frontend) are now properly and always called before displaying data to the front, even if you don’t transform your data with `$this->transform()` method.