Add parsed YAML is too big section

doc/administration/instance_limits.md

@@ -584,20 +584,25 @@ Plan.default.actual_limits.update!(dast_profile_schedules: 50)
 
 ### Maximum size and depth of CI/CD configuration YAML files
 
-The default maximum size of a CI/CD configuration YAML file is 1 megabyte and the default depth is 100.
+The default maximum size of a CI/CD configuration YAML file is 1 megabyte and the
+default depth is 100.
 
-You can change these limits in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session).
-Update `max_yaml_size_bytes` with the new value in megabytes:
+You can change these limits in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
-```ruby
-ApplicationSetting.update!(max_yaml_size_bytes: 2.megabytes)
-```
+- To update the maximum YAML size, update `max_yaml_size_bytes` with the new value in megabytes:
 
-Update `max_yaml_depth` with the new value in megabytes:
+  ```ruby
+  ApplicationSetting.update!(max_yaml_size_bytes: 2.megabytes)
+  ```
 
-```ruby
-ApplicationSetting.update!(max_yaml_depth: 125)
-```
+  The `max_yaml_size_bytes` value is not directly tied to the size of the YAML file,
+  but rather the memory allocated for the relevant objects.
+
+- To update the maximum YAML depth, update `max_yaml_depth` with the new value in megabytes:
+
+  ```ruby
+  ApplicationSetting.update!(max_yaml_depth: 125)
+  ```
 
 To disable this limitation entirely, disable the feature flag in the console:
 

doc/ci/troubleshooting.md

@@ -261,6 +261,24 @@ To resolve this, check that:
   that contain the included files. Users must also have the [permission](../user/permissions.md#job-permissions)
   to run CI/CD jobs in the same projects.
 
+### "The parsed YAML is too big" message
+
+This message displays when the YAML configuration is too large or nested too deeply.
+YAML files with a large number of includes, and thousands of lines overall, are
+more likely to hit this memory limit. For example, a YAML file that is 200kb is
+likely to hit the default memory limit.
+
+To reduce the configuration size, you can:
+
+- Check the length of the expanded CI/CD configuration in the pipeline editor's
+  [merged YAML](pipeline_editor/index.md#view-expanded-configuration) tab. Look for
+  duplicated configuration that can be removed or simplified.
+- Move long or repeated `script` sections into standalone scripts in the project.
+- Use [parent and child pipelines](pipelines/parent_child_pipelines.md) to move some
+  work to jobs in an independent child pipeline.
+
+On a self-managed instance, you can [increase the size limits](../administration/instance_limits.md#maximum-size-and-depth-of-cicd-configuration-yaml-files).
+
 ## Pipeline warnings
 
 Pipeline configuration warnings are shown when you: