docs: Recommend that hold_current not be specified

Changing motor current may itself introduce unwanted motor movement.
As such, document that specifying a hold_current is not recommended.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

docs/Config_Reference.md

@@ -2773,8 +2773,9 @@ run_current:
 #   during stepper movement. This parameter must be provided.
 #hold_current:
 #   The amount of current (in amps RMS) to configure the driver to use
-#   when the stepper is not moving. The default is to not reduce the
+#   when the stepper is not moving. Setting a hold_current is not
-#   current.
+#   recommended (see TMC_Drivers.md for details). The default is to
+#   not reduce the current.
 #sense_resistor: 0.110
 #   The resistance (in ohms) of the motor sense resistor. The default
 #   is 0.110 ohms.
@@ -2839,8 +2840,9 @@ run_current:
 #   during stepper movement. This parameter must be provided.
 #hold_current:
 #   The amount of current (in amps RMS) to configure the driver to use
-#   when the stepper is not moving. The default is to use the same
+#   when the stepper is not moving. Setting a hold_current is not
-#   value as run_current.
+#   recommended (see TMC_Drivers.md for details). The default is to
+#   not reduce the current.
 #sense_resistor: 0.110
 #   The resistance (in ohms) of the motor sense resistor. The default
 #   is 0.110 ohms.
@@ -3022,8 +3024,9 @@ run_current:
 #   during stepper movement. This parameter must be provided.
 #hold_current:
 #   The amount of current (in amps RMS) to configure the driver to use
-#   when the stepper is not moving. The default is to use the same
+#   when the stepper is not moving. Setting a hold_current is not
-#   value as run_current.
+#   recommended (see TMC_Drivers.md for details). The default is to
+#   not reduce the current.
 #sense_resistor: 0.075
 #   The resistance (in ohms) of the motor sense resistor. The default
 #   is 0.075 ohms.

docs/TMC_Drivers.md

@@ -11,6 +11,53 @@ this document are not available.
 In addition to this document, be sure to review the
 [TMC driver config reference](Config_Reference.md#tmc-stepper-driver-configuration).
 
+## Tuning motor current
+
+A higher driver current increases positional accuracy and torque.
+However, a higher current also increases the heat produced by the
+stepper motor and the stepper motor driver. If the stepper motor
+driver gets too hot it will disable itself and Klipper will report an
+error. If the stepper motor gets too hot, it loses torque and
+positional accuracy. (If it gets very hot it may also melt plastic
+parts attached to it or near it.)
+
+As a general tuning tip, prefer higher current values as long as the
+stepper motor does not get too hot and the stepper motor driver does
+not report warnings or errors. In general, it is okay for the stepper
+motor to feel warm, but it should not become so hot that it is painful
+to touch.
+
+## Prefer to not specify a hold_current
+
+If one configures a `hold_current` then the TMC driver can reduce
+current to the stepper motor when it detects that the stepper is not
+moving. However, changing motor current may itself introduce motor
+movement. This may occur due to "detent forces" within the stepper
+motor (the permanent magnet in the rotor pulls towards the iron teeth
+in the stator) or due to external forces on the axis carriage.
+
+Most stepper motors will not obtain a significant benefit to reducing
+current during normal prints, because few printing moves will leave a
+stepper motor idle for sufficiently long to activate the
+`hold_current` feature. And, it is unlikely that one would want to
+introduce subtle print artifacts to the few printing moves that do
+leave a stepper idle sufficiently long.
+
+If one wishes to reduce current to motors during print start routines,
+then consider issuing
+[SET_TMC_CURRENT](G-Codes.md#tmc-stepper-drivers) commands in a
+[START_PRINT macro](Slicers.md#klipper-gcode_macro) to adjust the
+current before and after normal printing moves.
+
+Some printers with dedicated Z motors that are idle during normal
+printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no
+"vase mode" prints, etc.) may find that Z motors do run cooler with a
+`hold_current`. If implementing this then be sure to take into account
+this type of uncommanded Z axis movement during bed leveling, bed
+probing, probe calibration, and similar. The `driver_TPOWERDOWN` and
+`driver_IHOLDDELAY` should also be calibrated accordingly. If unsure,
+prefer to not specify a `hold_current`.
+
 ## Enabling "StealthChop" Mode
 
 By default, Klipper places the TMC drivers in "spreadCycle" mode. If