treewide: fix typos and grammatical errors

Author: siraben

CONTRIBUTING.md

@@ -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

source/acknowledgements/index.md

@@ -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.

source/concepts/faq.md

@@ -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.

source/concepts/flakes.md

@@ -42,23 +42,23 @@ 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).
+  - 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).
 - As [predicted by RFC reviewers](https://github.com/NixOS/rfcs/pull/49#issuecomment-588990425), the original implementation introduced [regressions](https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257) in the [Nix 2.4 release](https://nix.dev/manual/nix/stable/release-notes/rl-2.4.html), breaking some stable functionality without a [major version](https://semver.org/) increment.
 - Copying sources to the Nix store prior to evaluation adds a [significant performance penalty](https://github.com/NixOS/nix/issues/3121), especially for large repositories such as {term}`Nixpkgs`.
@@ -75,7 +75,7 @@ As of the [2023](https://discourse.nixos.org/t/nix-community-survey-2023-results
 
 You have to judge for yourself based on your needs.
 
-[Flakes](flakes-definition) emphasize reproducible artifacts and convenience for their consumers, while classic Nix tools center around composable building blocks and customisation options for developers.
+[Flakes](flakes-definition) emphasize reproducible artifacts and convenience for their consumers, while classic Nix tools center around composable building blocks and customization options for developers.
 Both paradigms have their own set of unique concepts and support tooling that have to be learned, with varying ease of use, implementation quality, and support status.
 At the moment, neither the stable nor the experimental interface is clearly superior to the other in all aspects.
 
@@ -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:
 

source/concepts/index.md

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

source/contributing/documentation/diataxis.md

@@ -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"
 

source/contributing/documentation/index.md

@@ -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

source/contributing/documentation/resources.md

@@ -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
 

source/contributing/documentation/style-guide.md

@@ -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
 

source/contributing/documentation/writing-a-tutorial.md

@@ -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.