diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 957037b95f4f..809f397407a7 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -204,25 +204,9 @@ following are specific to `buildPythonPackage`:
 * `setupPyGlobalFlags ? []`: List of flags passed to `setup.py` command.
 * `setupPyBuildFlags ? []`: List of flags passed to `setup.py build_ext` command.
 
-##### Using fixed-point arguments {#buildpythonpackage-fixed-point-arguments}
+##### Writing override-compatible packages {#buildpythonpackage-fixed-point-arguments}
 
-Both `buildPythonPackage` and `buildPythonApplication` support [fixed-point arguments](#chap-build-helpers-finalAttrs), similar to `stdenv.mkDerivation`.
-This allows you to reference the final attributes of the derivation.
-
-Instead of using `rec`:
-
-```nix
-buildPythonPackage rec {
-  pname = "pyspread";
-  version = "2.4";
-  src = fetchPypi {
-    inherit pname version;
-    hash = "sha256-...";
-  };
-}
-```
-
-You can use the `finalAttrs` pattern:
+Use `finalAttrs` to make a package easy to update and override:
 
 ```nix
 buildPythonPackage (finalAttrs: {
@@ -236,7 +220,9 @@ buildPythonPackage (finalAttrs: {
 })
 ```
 
-See the [general documentation on fixed-point arguments](#chap-build-helpers-finalAttrs) for more details on the benefits of this pattern.
+When a downstream callsite *overrides* `version` the override becomes visible as `finalAttrs.version`.
+
+Both `buildPythonPackage` and `buildPythonApplication` support [fixed-point arguments](#chap-build-helpers-finalAttrs), similar to `stdenv.mkDerivation`.
 
 ::: {.note}