From f3494be6cc1c7fbfd5da7aa5315fa1e1f0dc2e46 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Fri, 28 Aug 2026 09:52:05 -0400
Subject: [PATCH] docs(nix): apply writing conventions

---
 docs/nix.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/nix.md b/docs/nix.md
index 8212454..6bd2b90 100644
--- a/docs/nix.md
+++ b/docs/nix.md
@@ -1,7 +1,7 @@
 # Nix Conventions
 
 This document records local Nix style and design conventions.
-Prefer these conventions when changing this flake.
+Use these conventions when changing this flake.
 
 ## Names
 
@@ -33,10 +33,10 @@ Use:
 
 ### Use closed interfaces for helper imports
 
-Use exact function argument patterns when an imported helper file has a closed interface.
-A helper file has a closed interface when the importer owns the argument set.
-The imported file must name each accepted attribute.
-This rejects stale or accidental extra attributes.
+Use exact function argument patterns for helper imports with closed interfaces.
+A helper import has a closed interface when the caller owns the argument set.
+The imported file names each accepted attribute.
+It rejects stale or accidental extra attributes.
 
 Avoid:
 
@@ -82,7 +82,7 @@ import ./flake {
 
 ### Keep NixOS module interfaces open
 
-NixOS modules must accept extra arguments because the module system owns their argument shape.
+NixOS modules accept extra arguments because the module system owns their argument shape.
 Name the arguments the module uses.
 Keep `...` so the module accepts standard module arguments and special arguments.
 
@@ -111,7 +111,7 @@ Use:
 
 ### Use `@` for forwarding wrappers
 
-Use `@` when a wrapper must pass the complete argument set to another module function.
+Use `@` when a wrapper passes the complete argument set to another module function.
 Name the arguments the wrapper uses before `...`.
 Forward the bound argument set unchanged.
 
@@ -134,7 +134,7 @@ dotfiles.guest { name = "sample"; } args
 ### Use `let` for important intermediate values
 
 Use a `let` binding when it names an important intermediate value.
-Use a `let` binding when it avoids repeating a complex expression.
+Use a `let` binding when it avoids repeated complex expressions.
 Do not use a `let` binding only to shorten a standard library call.
 
 Avoid:
@@ -156,7 +156,7 @@ lib.mapAttrs f attrs
 
 ### Qualify standard library calls in flake assembly
 
-Prefer qualified standard library calls inside flake assembly code.
+Use qualified standard library calls inside flake assembly code.
 Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
 This keeps the source of helper functions visible.
 
@@ -181,9 +181,9 @@ lib.mapAttrs f attrs
 
 Keep flake assembly code under `flake/`.
 Keep `flake.nix` focused on inputs and public outputs.
-A public output is any attribute returned by the flake `outputs` function.
-Another flake can reference a public output through `inputs.<name>.<output>`.
-Tools such as `nix flake show` also display public outputs.
+The `outputs` function returns each public output as an attribute.
+An external flake reads public outputs through `inputs.<name>.<output>`.
+`nix flake show` also displays public outputs.
 
 Avoid: