Repository: altair-viz/altair

Issue:
doc: ValueError: Faceted charts cannot be layered.
The error: `ValueError: Faceted charts cannot be layered.` is an often reoccurring error:
- https://github.com/altair-viz/altair/issues/2862 
- https://github.com/altair-viz/altair/issues/1570
- https://github.com/altair-viz/altair/issues/1329
- https://github.com/altair-viz/altair/issues/1147
- https://github.com/altair-viz/altair/issues/785

How can we improve the error message and/or improve the documentation, so that this is explained a bit better?

Discussion:

Patch:
diff --git a/altair/vegalite/v5/api.py b/altair/vegalite/v5/api.py
index 5b11d029..4ca266f4 100644
--- a/altair/vegalite/v5/api.py
+++ b/altair/vegalite/v5/api.py
@@ -2272,24 +2272,38 @@ def _check_if_can_be_layered(spec):
     if encoding is not Undefined:
         for channel in ["row", "column", "facet"]:
             if _get(encoding, channel) is not Undefined:
-                raise ValueError("Faceted charts cannot be layered.")
+                raise ValueError(
+                    "Faceted charts cannot be layered. Instead, layer the charts before faceting."
+                )
     if isinstance(spec, (Chart, LayerChart)):
         return
 
     if not isinstance(spec, (core.SchemaBase, dict)):
         raise ValueError("Only chart objects can be layered.")
     if _get(spec, "facet") is not Undefined:
-        raise ValueError("Faceted charts cannot be layered.")
+        raise ValueError(
+            "Faceted charts cannot be layered. Instead, layer the charts before faceting."
+        )
     if isinstance(spec, FacetChart) or _get(spec, "facet") is not Undefined:
-        raise ValueError("Faceted charts cannot be layered.")
+        raise ValueError(
+            "Faceted charts cannot be layered. Instead, layer the charts before faceting."
+        )
     if isinstance(spec, RepeatChart) or _get(spec, "repeat") is not Undefined:
-        raise ValueError("Repeat charts cannot be layered.")
+        raise ValueError(
+            "Repeat charts cannot be layered. Instead, layer the charts before repeating."
+        )
     if isinstance(spec, ConcatChart) or _get(spec, "concat") is not Undefined:
-        raise ValueError("Concatenated charts cannot be layered.")
+        raise ValueError(
+            "Concatenated charts cannot be layered. Instead, layer the charts before concatenating."
+        )
     if isinstance(spec, HConcatChart) or _get(spec, "hconcat") is not Undefined:
-        raise ValueError("Concatenated charts cannot be layered.")
+        raise ValueError(
+            "Concatenated charts cannot be layered. Instead, layer the charts before concatenating."
+        )
     if isinstance(spec, VConcatChart) or _get(spec, "vconcat") is not Undefined:
-        raise ValueError("Concatenated charts cannot be layered.")
+        raise ValueError(
+            "Concatenated charts cannot be layered. Instead, layer the charts before concatenating."
+        )
 
 
 @utils.use_signature(core.TopLevelRepeatSpec)


Test patch:
diff --git a/tests/vegalite/v5/tests/test_api.py b/tests/vegalite/v5/tests/test_api.py
index 12e8b666..b4b82a17 100644
--- a/tests/vegalite/v5/tests/test_api.py
+++ b/tests/vegalite/v5/tests/test_api.py
@@ -944,17 +944,33 @@ def test_layer_errors():
         'Objects with "config" attribute cannot be used within LayerChart.'
     )
 
+    with pytest.raises(ValueError) as err:
+        alt.hconcat(simple_chart) + simple_chart
+    assert (
+        str(err.value)
+        == "Concatenated charts cannot be layered. Instead, layer the charts before concatenating."
+    )
+
     with pytest.raises(ValueError) as err:
         repeat_chart + simple_chart
-    assert str(err.value) == "Repeat charts cannot be layered."
+    assert (
+        str(err.value)
+        == "Repeat charts cannot be layered. Instead, layer the charts before repeating."
+    )
 
     with pytest.raises(ValueError) as err:
         facet_chart1 + simple_chart
-    assert str(err.value) == "Faceted charts cannot be layered."
+    assert (
+        str(err.value)
+        == "Faceted charts cannot be layered. Instead, layer the charts before faceting."
+    )
 
     with pytest.raises(ValueError) as err:
         alt.layer(simple_chart) + facet_chart2
-    assert str(err.value) == "Faceted charts cannot be layered."
+    assert (
+        str(err.value)
+        == "Faceted charts cannot be layered. Instead, layer the charts before faceting."
+    )
 
 
 @pytest.mark.parametrize(