1 files changed, 25 insertions, 7 deletions
diff --git a/nixpkgs/nixos/doc/manual/development/option-def.section.md b/nixpkgs/nixos/doc/manual/development/option-def.section.md
index 91b24cd4a3a1..6a3dc26b99be 100644
--- a/nixpkgs/nixos/doc/manual/development/option-def.section.md
+++ b/nixpkgs/nixos/doc/manual/development/option-def.section.md
@@ -12,7 +12,7 @@ config = {
 However, sometimes you need to wrap an option definition or set of
 option definitions in a *property* to achieve certain effects:
 
-## Delaying Conditionals {#sec-option-definitions-delaying-conditionals .unnumbered}
+## Delaying Conditionals {#sec-option-definitions-delaying-conditionals}
 
 If a set of option definitions is conditional on the value of another
 option, you may need to use `mkIf`. Consider, for instance:
@@ -56,22 +56,40 @@ config = {
 };
 ```
 
-## Setting Priorities {#sec-option-definitions-setting-priorities .unnumbered}
+## Setting Priorities {#sec-option-definitions-setting-priorities}
 
 A module can override the definitions of an option in other modules by
-setting a *priority*. All option definitions that do not have the lowest
+setting an *override priority*. All option definitions that do not have the lowest
 priority value are discarded. By default, option definitions have
-priority 1000. You can specify an explicit priority by using
-`mkOverride`, e.g.
+priority 100 and option defaults have priority 1500.
+You can specify an explicit priority by using `mkOverride`, e.g.
 
 ```nix
 services.openssh.enable = mkOverride 10 false;
 ```
 
 This definition causes all other definitions with priorities above 10 to
-be discarded. The function `mkForce` is equal to `mkOverride 50`.
+be discarded. The function `mkForce` is equal to `mkOverride 50`, and
+`mkDefault` is equal to `mkOverride 1000`.
 
-## Merging Configurations {#sec-option-definitions-merging .unnumbered}
+## Ordering Definitions {#sec-option-definitions-ordering}
+
+It is also possible to influence the order in which the definitions for an option are
+merged by setting an *order priority* with `mkOrder`. The default order priority is 1000.
+The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1500`, respectively.
+As an example,
+
+```nix
+hardware.firmware = mkBefore [ myFirmware ];
+```
+
+This definition ensures that `myFirmware` comes before other unordered
+definitions in the final list value of `hardware.firmware`.
+
+Note that this is different from [override priorities](#sec-option-definitions-setting-priorities):
+setting an order does not affect whether the definition is included or not.
+
+## Merging Configurations {#sec-option-definitions-merging}
 
 In conjunction with `mkIf`, it is sometimes useful for a module to
 return multiple sets of option definitions, to be merged together as if