[GR-19691] Improve documentation about benchmarking

Author: eregon

doc/user/benchmarking.md

@@ -32,6 +32,14 @@ The Native configuration provides better startup and warmup but has slower peak
 
 Of course you can also benchmark both configurations and see which one is better for what you are benchmarking.
 
+### Run with Enough Warmup
+
+TruffleRuby like other runtimes with a just-in-time compiler needs some time (called warmup) to reach peak performance,
+because it takes time to just-in-time compile the relevant methods of the benchmark.
+The easiest way to check if there was enough warmup is to run the benchmark workload repeatedly inside a process and print the times of each run.
+The times should be very stable once it's warmed up and conversely keep changing while it is not warmed up yet.
+See [this documentation](reporting-performance-problems.md) for more details about warmup.
+
 ### Consider Disabling the Global C-Extension Lock
 
 On TruffleRuby, C extensions by default use a global lock for maximum compatibility with CRuby.
@@ -85,6 +93,13 @@ Restricting it to a single core for benchmarking does not make sense, it would c
 
 ### Avoid Benchmarking on macOS
 
-macOS's memory management is sub-par and can cause unnecessary memory swapping even when there is enough memory.
+macOS's memory management is subpar and can cause unnecessary memory swapping even when there is enough memory (e.g. it sometimes keeps terminated processes in memory needlessly).
+
+macOS's TCP stack is also subpar, see the [Passenger docs](https://www.phusionpassenger.com/library/config/apache/optimization/#operating-system-recommendations) on this subject.
 
-macOS's TCP stack is also sub-par, see the [Passenger docs](https://www.phusionpassenger.com/library/config/apache/optimization/#operating-system-recommendations) on this subject.
+If you have no choice but to benchmark on macOS then mention that with the results
+and ensure there is plenty free memory and no swap while benchmarking.
+Use `vm_stat` (`Pages free`) or `top` (`PhysMem` -> `unused`) to check the amount of free memory.
+Unfortunately neither of these tools show the swap usage, illustrating how difficult it is to ensure there is no swapping going on when benchmarking on macOS.
+Use `Activity Monitor` before and after benchmarking to ensure there is no swap (`Swap Used`) as a workaround.
+`Activity Monitor` is too heavy to be used during benchmarking.