docs: more context around shm-size and ulimit usage

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>

docs/bake-reference.md

@@ -836,6 +836,9 @@ RUN --mount=type=secret,id=KUBECONFIG \
 
 ### `target.shm-size`
 
+Sets the size of the shared memory allocated for build's containers when using
+`RUN` instructions.
+
 The format is `<number><unit>`. `number` must be greater than `0`. Unit is
 optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
 (gigabytes). If you omit the unit, the system uses bytes.
@@ -848,6 +851,11 @@ target "default" {
 }
 ```
 
+> **Note**
+> In most cases, it is recommended to let the builder automatically determine
+> the appropriate configurations. Manual adjustments should only be considered
+> when specific performance tuning is required for complex build scenarios.
+
 ### `target.ssh`
 
 Defines SSH agent sockets or keys to expose to the build.
@@ -896,7 +904,8 @@ target "default" {
 
 ### `target.ulimits`
 
-Ulimits are specified with a soft and hard limit as such:
+Ulimits overrides the default ulimits of build's containers when using `RUN`
+instructions and are specified with a soft and hard limit as such:
 `<type>=<soft limit>[:<hard limit>]`, for example:
 
 ```hcl
@@ -913,6 +922,11 @@ target "app" {
 > for both values. If no `ulimits` are set, they are inherited from
 > the default `ulimits` set on the daemon.
 
+> **Note**
+> In most cases, it is recommended to let the builder automatically determine
+> the appropriate configurations. Manual adjustments should only be considered
+> when specific performance tuning is required for complex build scenarios.
+
 ## Group
 
 Groups allow you to invoke multiple builds (targets) at once.

docs/reference/buildx_build.md

@@ -655,10 +655,18 @@ $ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
 
 ### <a name="shm-size"></a> Size of /dev/shm (--shm-size)
 
+Sets the size of the shared memory allocated for build's containers when using
+`RUN` instructions.
+
 The format is `<number><unit>`. `number` must be greater than `0`. Unit is
 optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
 (gigabytes). If you omit the unit, the system uses bytes.
 
+> **Note**
+> In most cases, it is recommended to let the builder automatically determine
+> the appropriate configurations. Manual adjustments should only be considered
+> when specific performance tuning is required for complex build scenarios.
+
 ### <a name="ssh"></a> SSH agent socket or keys to expose to the build (--ssh)
 
 ```text
@@ -692,7 +700,8 @@ $ docker buildx build --ssh default=$SSH_AUTH_SOCK .
 
 ### <a name="ulimit"></a> Set ulimits (--ulimit)
 
-`--ulimit` is specified with a soft and hard limit as such:
+`--ulimit` overrides the default ulimits of build's containers when using `RUN`
+instructions and are specified with a soft and hard limit as such:
 `<type>=<soft limit>[:<hard limit>]`, for example:
 
 ```console
@@ -704,3 +713,8 @@ $ docker buildx build --ulimit nofile=1024:1024 .
 > If you don't provide a `hard limit`, the `soft limit` is used
 > for both values. If no `ulimits` are set, they're inherited from
 > the default `ulimits` set on the daemon.
+
+> **Note**
+> In most cases, it is recommended to let the builder automatically determine
+> the appropriate configurations. Manual adjustments should only be considered
+> when specific performance tuning is required for complex build scenarios.