NixOS · siraben · Sep 10, 2025 · djacu · Sep 12, 2025 · siraben
@@ -29,7 +29,7 @@ To manually test [redirects](./_redirects):
 
 ## Building the reference manuals
 
-By default nix.dev builds without the various versions of the Nix reference manual, as that takes quite a while due to how it's currently implemented.
+By default, nix.dev builds without the various versions of the Nix reference manual, as that takes quite a while due to how it's currently implemented.
 To enable building the manuals:
 
 ```shell-session

@@ -38,4 +38,4 @@ Many thanks to past contributors, who helped make Nix documentation what it is t
 - [@domenkozar](https://github.com/domenkozar) was a founding member and part of the team from 2022-05 to 2023-01.
   Domen originally started nix.dev, wrote many basic tutorials, and funded editorial work through [Cachix](https://www.cachix.org/).
   He helped bootstrap the documentation team, handed out permissions, and advised us on many aspects.
-  Domen donated nix.dev to the NixOS Foundation 2023-07.
+  Domen donated nix.dev to the NixOS Foundation in 2023-07.
@@ -62,12 +62,12 @@ Rolling releases follow [`master`](https://github.com/NixOS/nixpkgs/branches/all
 
 Yes. There is:
 
-- CPU architecture—great effort being made to avoid compilation of native instructions in favour of hardcoded supported ones.
+- CPU architecture—great effort is being made to avoid compilation of native instructions in favour of hardcoded supported ones.
 - System's current time/date.
 - The filesystem used for building (see also [`TMPDIR`](https://nix.dev/manual/nix/stable/command-ref/env-common.html#env-TMPDIR)).
 - Linux kernel parameters, such as:
   - [IPv6 capabilities](https://github.com/NixOS/nix/issues/5615).
   - binfmt interpreters, e.g., those configured with [`boot.binfmt.emulatedSystems`](https://search.nixos.org/options?show=boot.binfmt.emulatedSystems).
-- Timing behaviour of the build system—parallel Make build does not get the correct inputs in some cases.
+- Timing behaviour of the build system—a parallel Make build may not get the correct inputs in some cases.
 - Insertion of random values, e.g., from `/dev/random` or `/dev/urandom`.
 - Differences between Nix versions. For instance, a new Nix version might introduce a new environment variable. A statement like `env > $out` is not promised by Nix to result in the same output, going into the future.
@@ -42,21 +42,21 @@ Nix handles flakes differently than regular {term}`Nix files <Nix file>` in the
 
 - No external variables, parameters, or impure language values are allowed.
 
-  It means full reproducibility of a Nix expression, and, by extension, the resulting build instructions by default, but also prohibits parameterisation of results by consumers.
+  It means full reproducibility of a Nix expression, and, by extension, the resulting build instructions by default, but also prohibits parametrisation of results by consumers.
 
 (flakes-controversy)=
 ## Why are flakes controversial?
 
 [Flakes](flakes-definition) were inspired by [Shea Levy's NixCon 2018 talk](https://www.youtube.com/watch?v=DHOLjsyXPtM), formally proposed in [RFC 49](https://github.com/NixOS/rfcs/pull/49), and have been in development since 2019.
 Nix introduced the implementation as its first [experimental feature] in 2021.
 
-The subject is considered controversial among Nix users and developers in terms of design, implementation quality, and decision making process.
+The subject is considered controversial among Nix users and developers in terms of design, implementation quality, and decision-making process.
 In particular:
 - The RFC was closed without conclusion, and some fundamental issues are not yet resolved.
   For example:
   - The notion of a [global flake registry](https://github.com/NixOS/flake-registry) saw [substantial criticism](https://github.com/NixOS/rfcs/pull/49#issuecomment-635635333) that was never addressed.
     While the source references of [registry entries can be pinned](https://nix.dev/manual/nix/stable/command-ref/new-cli/nix3-registry-pin), local registry names in Nix expressions [introduce mutable system state](https://github.com/NixOS/nix/issues/7422) and are thus, in that regard, no improvement over channels as managed by [`nix-channel`](https://nix.dev/manual/nix/stable/command-ref/nix-channel).
-  - It is [impossible to parameterise flakes](https://github.com/NixOS/nix/issues/2861).
+  - It is [impossible to parametrise flakes](https://github.com/NixOS/nix/issues/2861).
     This means that [flakes downgrade ease of use of the `system` parameter](https://github.com/NixOS/nix/issues/3843) of derivations, for producers and consumers.
   - the flakes proposal was criticised for [trying to solve too many problems at once](https://github.com/nixos/rfcs/pull/49#issuecomment-521998933) and [at the wrong abstraction layer](https://discourse.nixos.org/t/nixpkgs-cli-working-group-member-search/30517).
     Part of this is that [the new command line interface and flakes are closely tied to each other](https://discourse.nixos.org/t/2023-03-06-nix-team-meeting-minutes-38/26056#cli-stabilisation-announcement-draft-4).
@@ -89,13 +89,13 @@ Flakes and the `nix` command suite bring multiple improvements that are relevant
 At the same time, flakes have [fundamental architectural issues](flakes-controversy) and a number of [problems with the implementation](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+label%3Aflakes+sort%3Areactions-%2B1-desc), and there is no coordinated effort to resolve them systematically.
 There are also still many [open design questions around the `nix` command line interface](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+label%3Anew-cli+sort%3Areactions-%2B1-desc), some of which are currently being worked on.
 
-While flakes reduce complexity in some regards, they also introduce some with additional mechanisms.
+While flakes reduce complexity in some regards, they also introduce some complexity with additional mechanisms.
 You will have to learn more about the system to fully understand how it works.
 
 Other than that, and below the surface of the flake schema, Nix and the Nix language work exactly the same in both cases.
 In principle, the same level of reproducibility can be achieved with or without flakes.
 In particular, the process of adding software to {term}`Nixpkgs` or maintaining {term}`NixOS` modules and configurations is not affected by flakes at all.
-There is also no evidence that flakes could help solving the scalability challenges of either.
+There is also no evidence that flakes could help solve the scalability challenges of either.
 
 Finally, there are downsides to relying on [experimental features][experimental feature] in general:
 

@@ -1,7 +1,7 @@
 (concepts)=
 # Concepts
 
-These sections contains explanations of history and ideas in the Nix ecosystem.
+These sections contain explanations of history and ideas in the Nix ecosystem.
 
 ```{toctree}
 :glob:

@@ -5,9 +5,9 @@ We aim to build our documentation according to the [Diátaxis framework for tech
 - [Tutorials](#tutorials)
 - [Guides](#guides)
 - [Reference](#reference)
-- [Concept](#concepts)
+- [Concepts](#concepts)
 
-We've found that contributors struggle to understand the differences between these categories, and while we _strongly_ recommend reading up on the Diataxis framework, we can summarize them as follows:
+We've found that contributors struggle to understand the differences between these categories, and while we _strongly_ recommend reading up on the Diátaxis framework, we can summarize them as follows:
 
 ## Reference
 
@@ -62,7 +62,7 @@ The pilot-in-training needs practice knowing when to deploy the landing gear, wh
 Actually landing the plane during the flight simulation is less important than learning the individual skills that make up a successful landing.
 This is the context for a tutorial.
 
-Finally, one last way of thinking about the difference between How-to Guide and Tutorial is like this:
+Finally, one last way of thinking about the difference between a how-to guide and a tutorial is like this:
 - Guide: "step 1: do this, step 2: do that, etc"
 - Tutorial: "take my hand as I show you how to do this"
 
@@ -1,6 +1,6 @@
 # Contributing documentation
 
-Thank you for your interest to help improve documentation in the Nix ecosystem!
+Thank you for your interest in helping improve documentation in the Nix ecosystem!
 This project would not be possible without your support.
 
 ## Getting started
@@ -40,7 +40,7 @@ Please share your experience to help us improve upstream documentation and begin
 If you are proficient in applying Nix to a domain-specific problem, and want to share your expertise on best practices, please check the existing content.
 - Does existing material on your subject meet your standards?
 - How could we improve it?
-- Is there a popular application of Nix' capabilities not yet covered?
+- Is there a popular application of Nix's capabilities not yet covered?
 - We would be glad to incorporate your insights.
 
 ## Licensing and attribution

@@ -1,6 +1,6 @@
 # Documentation resources
 
-This is an overview of documentation resources for Nix, Nixpkgs, and NixOS, with suggestions how you can help to improve them.
+This is an overview of documentation resources for Nix, Nixpkgs, and NixOS, with suggestions for how you can help to improve them.
 
 ## Reference manuals
 

@@ -10,8 +10,8 @@ This document outlines the guidelines we use when writing documentation.
 >
 > — [Blaise Pascal](https://en.m.wikiquote.org/w/index.php?title=Blaise_Pascal&oldid=2978584#Quotes)
 
-Readers' time and attention is limited.
-Take the time to be extraordinarily respectful with their cognitive resources.
+Readers' time and attention are limited.
+Take the time to be extraordinarily respectful of their cognitive resources.
 
 The same holds for communication directed to contributors and maintainers:
 This is a public project, and many people will read what you write.
@@ -27,7 +27,7 @@ Use this leverage with care.
 
   > Add the `python310` package to `buildInputs`.
 
-  Don't use a conversational tone, as it distracts from the contents.
+  Don't use a conversational tone, as it distracts from the content.
   For example, don't write:
 
   > Going forward, let's now add the `python310` package to `buildInputs` as we have seen in the previous tutorial.
@@ -110,7 +110,7 @@ Set off a [fork bomb](https://en.wikipedia.org/wiki/Fork_bomb):
 ```
 
 :::{dropdown} Detailed explanation
-This Bash command defines and executes a function `:` that recursively spawns copies of itself, quickly consuming system resources
+This Bash command defines and executes a function `:` that recursively spawns copies of itself, quickly consuming system resources.
 :::
 ````
 ::::
@@ -126,10 +126,10 @@ If that's not possible, break the example down into multiple parts, explain them
 
 Code samples that are _intended_ to work should work.
 
-If you are going to present an example that does not work (e.g. you're illustrating a common mistake) explain so beforehand.
+If you are going to present an example that does not work (e.g. you're illustrating a common mistake) explain this beforehand.
 Many readers will get stuck trying to make example code work without reading ahead to find out that the code isn't intended to work.
 
-Code samples should all include a programming language when applicable for syntax highlighting when rendered e.g.
+Code samples should all include a programming language when applicable for syntax highlighting when rendered, e.g.:
 
 ````
 ```python
@@ -142,7 +142,7 @@ print("Hello, World!")
 Reserve the largest header (`#`) for the title.
 
 Use Markdown headers `##` through `###` to divide up content in the body of the document.
-Finer grained headings are not necessarily better.
+Finer-grained headings are not necessarily better.
 
 ### One line per sentence
 

@@ -24,20 +24,20 @@ Most of that time is typically spent collaboratively:
 - Ensuring that the instructions are neither too sparse nor too dense for learners
 - Finding ever-more succinct and clear ways to convey ideas
 
-Follow these steps to avoid re-doing work
+Follow these steps to avoid redoing work
 
 ### Pick a topic
 
 There is a [tracking issue](https://github.com/NixOS/nix.dev/issues/572) for tutorials that the documentation team has decided should exist as part of the tutorial series.
 Pick an issue that covers a topic that you're either knowledgeable about or have a particular interest in.
 
-Check referenced issues and pull request to make sure you won't duplicate work that someone else has already started!
+Check referenced issues and pull requests to make sure you won't duplicate work that someone else has already started!
 
 There are more [tutorial requests](https://github.com/NixOS/nix.dev/issues?q=is%3Aopen+is%3Aissue+label%3Atutorial) than captured in the outline.
 [Open a new issue](https://github.com/NixOS/nix.dev/issues/new?&template=tutorial.md) if what you wanted to work on isn't tracked anywhere.
 This is an opportunity for you to clarify your goals, and an opportunity for everyone else to find out that there's interest in that subject.
 
-### Submit an pull request with an outline
+### Submit a pull request with an outline
 
 Submit a pull request with an outline of the tutorial following [our recommended structure](#structure).
 The outline should contain bullet points on each section's content.
@@ -57,7 +57,7 @@ Revise your tutorial based on the detailed feedback.
 We recommend testing your tutorial with friends or coworkers.
 This will both help with revealing implicit prerequisites as well as provide a realistic estimate of the reading time.
 
-In a final review will check that everything is technically correct.
+A final review will check that everything is technically correct.
 
 ## Structure
 
@@ -74,7 +74,7 @@ The learning goal of a tutorial is always acquiring a skill, which is distinguis
 ### What do you need?
 
 State the prerequisite knowledge and skills.
-The tutorial should always be written such that the stated prerequisites are sufficient to achieve learning goals.
+The tutorial should always be written such that the stated prerequisites are sufficient to achieve the learning goals.
 
 Examples:
 
@@ -111,7 +111,7 @@ Depending on how well a use case is explored, point the reader to
 - guides or other tutorials
 - links to known-good external resources, with summaries
 - overview of available support tools, and their state of maturity and maintenance
-- overview of ideas, and state of community discussion.
+- overview of ideas, and the state of community discussion.
 
 We recommend making an explicit separation of practical from theoretical learning resources, as then readers will be able to quickly decide to either get things done or learn more.
 

@@ -6,7 +6,7 @@ Keeping it working and up to date – and improving it continuously – would no
 
 This guide shows how you can contribute to {term}`Nix`, {term}`Nixpkgs` or {term}`NixOS`.
 It assumes that you're already somewhat proficient with basic concepts and workflows, which are outlined in the [beginner tutorial series](tutorials).
-The most important aspects are [the Nix language](reading-nix-language), the various Nixpkgs mechanisms for [constructing derivations to build software](packaging-tutorial)</a>, [the module system](module-system-tutorial), and [NixOS integration tests](integration-testing-vms).
+The most important aspects are [the Nix language](reading-nix-language), the various Nixpkgs mechanisms for [constructing derivations to build software](packaging-tutorial), [the module system](module-system-tutorial), and [NixOS integration tests](integration-testing-vms).
 
 :::{important}
 If you cannot contribute time, consider [donating to the NixOS Foundation on Open Collective](https://opencollective.com/nixos).
@@ -17,7 +17,7 @@ With enough budget, it would be possible to pay for ongoing maintenance and deve
 
 ## Getting started
 
-Start with asking informed questions, after reading [reference documentation](reference) and the code relevant to what you care about.
+Start by asking informed questions, after reading [reference documentation](reference) and the code relevant to what you care about.
 
 [Join our community communication platforms](https://nixos.org/community) to get in contact with other users and developers.
 Check out and consider participating in our [community teams](https://nixos.org/community/#governance-teams) if you're interested in a particular topic.
@@ -43,7 +43,7 @@ And it will lead to better code and documentation in the long run.
 :::{note}
 For asking general questions about the code or how to do things, please use our [community communication platforms](https://nixos.org/community)
 
-To state techincal problems and propose solutions, open GitHub issues and close them when the problem is resolved or invalidated.
+To state technical problems and propose solutions, open GitHub issues and close them when the problem is resolved or invalidated.
 :::
 
 We can only fix issues that we know of, so please report any issue you encounter.
@@ -78,7 +78,7 @@ The perfect issue is, in fact, a pull request that solves the problem directly a
 :::
 
 :::{important}
-Please open issues to request new features (such as packages, modules, commands, ...) only if your are willing and able to implement them yourself.
+Please open issues to request new features (such as packages, modules, commands, ...) only if you are willing and able to implement them yourself.
 Then the issue can be used to gauge user interest, to determine if the feature fits into the project, and to discuss implementation strategies.
 :::
 
@@ -117,6 +117,3 @@ If you know your way around, working on [popular issues][nixos issues] will be h
 
 [nixos issues]: https://github.com/NixOS/nixpkgs/issues?q=is%3Aopen+is%3Aissue+label%3A%226.topic%3A+nixos%22+sort%3Areactions-%2B1-desc
 
-# How to get help
-
-If you prepared a pull request and need help moving forward, check [](contributing-how-to-get-help) for
@@ -6,7 +6,7 @@ can go for help.
 
 ## How to find maintainers
 
-For better efficiency and higher chance of success, you should try contacting individuals or groups with more specific knowledge first:
+For better efficiency and a higher chance of success, you should try contacting individuals or groups with more specific knowledge first:
 
 - If your contribution is for a package in Nixpkgs, look for its maintainers in the
   [`maintainers`](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers)
@@ -28,7 +28,7 @@ Once you've found the people you're looking for, you can contact them on one of
   All the source code is maintained on GitHub.
   This is the right place to discuss implementation details.
 
-  In issue comments or pull request descriptions, [mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file][maintainers-list].
+  In issue comments or pull request descriptions, [mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file](https://github.com/NixOS/nixpkgs/blob/master/maintainers/maintainer-list.nix).
 
 - [Discourse](https://discourse.nixos.org)