diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 66fedd4bd34..36f5336209c 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -1397,10 +1397,12 @@
 			Lower-end override for [member rendering/quality/shading/force_lambert_over_burley] on mobile devices, due to performance concerns or driver support.
 		</member>
 		<member name="rendering/quality/shading/force_vertex_shading" type="bool" setter="" getter="" default="false">
-			If [code]true[/code], forces vertex shading for all rendering. This can increase performance a lot, but also reduces quality immensely. Can be used to optimize performance on low-end mobile devices.
+			If [code]true[/code], forces vertex shading for all 3D [SpatialMaterial] and [ShaderMaterial] rendering. This can be used to improve performance on low-end mobile devices. The downside is that shading becomes much less accurate, with visible linear interpolation between vertices that are joined together. This can be compensated by ensuring meshes have a sufficient level of subdivision (but not too much, to avoid reducing performance). Some material features are also not supported when vertex shading is enabled.
+			See also [member SpatialMaterial.flags_vertex_lighting] which can be used to enable vertex shading on specific materials only.
+			[b]Note:[/b] This setting does not affect unshaded materials.
 		</member>
 		<member name="rendering/quality/shading/force_vertex_shading.mobile" type="bool" setter="" getter="" default="true">
-			Lower-end override for [member rendering/quality/shading/force_vertex_shading] on mobile devices, due to performance concerns or driver support.
+			Lower-end override for [member rendering/quality/shading/force_vertex_shading] on mobile devices, due to performance concerns or driver support. If lighting looks broken after exporting the project to a mobile platform, try disabling this setting.
 		</member>
 		<member name="rendering/quality/shading/use_physical_light_attenuation" type="bool" setter="" getter="" default="false">
 			If [code]true[/code], enables new physical light attenuation for [OmniLight]s and [SpotLight]s. This results in more realistic lighting appearance with a very small performance cost. When physical light attenuation is enabled, lights will appear to be darker as a result of the new attenuation formula. This can be compensated by adjusting the lights' energy or attenuation values.
diff --git a/doc/classes/SpatialMaterial.xml b/doc/classes/SpatialMaterial.xml
index e0e95c7e76b..5f1dab0d4ca 100644
--- a/doc/classes/SpatialMaterial.xml
+++ b/doc/classes/SpatialMaterial.xml
@@ -208,7 +208,10 @@
 			If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR.
 		</member>
 		<member name="flags_vertex_lighting" type="bool" setter="set_flag" getter="get_flag" default="false">
-			If [code]true[/code], lighting is calculated per vertex rather than per pixel. This may increase performance on low-end devices.
+			If [code]true[/code], lighting is calculated per vertex rather than per pixel. This may increase performance on low-end devices, especially for meshes with a lower polygon count. The downside is that shading becomes much less accurate, with visible linear interpolation between vertices that are joined together. This can be compensated by ensuring meshes have a sufficient level of subdivision (but not too much, to avoid reducing performance). Some material features are also not supported when vertex shading is enabled.
+			See also [member ProjectSettings.rendering/quality/shading/force_vertex_shading] which can globally enable vertex shading on all materials.
+			[b]Note:[/b] By default, vertex shading is enforced on mobile platforms by [member ProjectSettings.rendering/quality/shading/force_vertex_shading]'s [code]mobile[/code] override.
+			[b]Note:[/b] [member flags_vertex_lighting] has no effect if [member flags_unshaded] is [code]true[/code].
 		</member>
 		<member name="flags_world_triplanar" type="bool" setter="set_flag" getter="get_flag" default="false">
 			If [code]true[/code], triplanar mapping is calculated in world space rather than object local space. See also [member uv1_triplanar].