diff --git a/docs/Parameters.rst b/docs/Parameters.rst
index 1e9eacf77e8b..e5c500ac7540 100644
--- a/docs/Parameters.rst
+++ b/docs/Parameters.rst
@@ -240,14 +240,18 @@ Core Parameters
- refer to `Distributed Learning Guide <./Parallel-Learning-Guide.rst>`__ to get more details
-- ``num_threads`` :raw-html:`🔗︎`, default = ``0``, type = int, aliases: ``num_thread``, ``nthread``, ``nthreads``, ``n_jobs``
+- ``num_threads`` :raw-html:`🔗︎`, default = ``None``, type = int, aliases: ``num_thread``, ``nthread``, ``nthreads``, ``n_jobs``
- used only in ``train``, ``prediction`` and ``refit`` tasks or in correspondent functions of language-specific packages
- number of threads for LightGBM
+ - ``None`` means number of physical cores
+
- ``0`` means default number of threads in OpenMP
+ - Negative integers are interpreted as following joblib's formula (``n_cpus + 1 + n_jobs``), just like scikit-learn (so e.g. -1 means using all cores, physical or logical).
+
- for the best speed, set this to the number of **real CPU cores**, not the number of threads (most CPUs use `hyper-threading `__ to generate 2 threads per CPU core)
- do not set it too large if your dataset is small (for instance, do not use 64 threads for a dataset with 10,000 rows)