Update documentation

README.md

@@ -34,7 +34,7 @@ If you know something about Nix, then these documents will help you get started
 
 The "main" branch of the GitHub repository has the latest released version of this code. There is currently no commitment to either forward or backward compatibility.
 
-"user/shajra" branches are personal branches that may be force-pushed to. The "main" branch should not experience force-pushes and is recommended for general use.
+"user/shajra" branches are personal branches that may be force-pushed. The "main" branch should not experience force-pushes and is recommended for general use.
 
 # License<a id="sec-3"></a>
 

README.org

@@ -39,9 +39,9 @@ The "main" branch of the GitHub repository has the latest released version of
 this code. There is currently no commitment to either forward or backward
 compatibility.
 
-"user/shajra" branches are personal branches that may be force-pushed to. The
-"main" branch should not experience force-pushes and is recommended for
-general use.
+"user/shajra" branches are personal branches that may be force-pushed. The
+"main" branch should not experience force-pushes and is recommended for general
+use.
 
 * License
 

doc/internal/nix-introduction-compat.org

@@ -6,19 +6,19 @@ project-dependent.
 
 * Helping non-flakes users
 
-A few users make work in organizations or contribute to projects that disallow
+A few users work in organizations or contribute to projects that disallow
 experimental features such as flakes.
 
-To buffer this compromise, this project uses and encourages the use of the
-[[nix-flake-compat][flake-compat]] project, which enables an end user who has opted not to enable
-flakes to at least access the flake's contents, packages or otherwise.
+For these users, this project uses and encourages the use of the [[nix-flake-compat][flake-compat]]
+project, which enables an end user who has opted not to enable flakes to at
+least access the flake's contents, packages or otherwise.
 
-With flake-compat, end users will have a normal (non-flake) Nix expression they
+With flake-compat, end users will have a regular (non-flake) Nix expression they
 can evaluate. However, since dependencies are managed with flakes, the project
 maintainer must have flakes enabled to manage dependencies (for example,
 updating to the latest dependencies with =nix flake update=).
 
-* Documenting an end user experience
+* Documenting an end-user experience
 
 To deal with the transition of the Nix community to flake, this project provides
 two user guides:
@@ -30,34 +30,36 @@ Links generally steer users to the recommended guide, which then links users to
 the non-flakes guide if they have the interest or need.
 
 The non-flakes guide intentionally avoids commands like =nix-shell= and
-=nix-channel=. These commands lead users to setting the =NIX_PATH= environment
-variable, which can lead to unreliable builds.
+=nix-channel=. These commands lead users to set the =NIX_PATH= environment
+variable, which can lead to unreliable builds.  These are the pitfalls that
+motivated the design of flakes.
 
-Though this guide avoid the =flakes= experimental feature, it still invites end
-users to use the experimental =nix-command= to get the following subcommands:
+Though this non-flakes guide avoids the =flakes= experimental feature, it still
+invites end users to use the experimental =nix-command= to get the following
+subcommands:
 - =nix search=
 - =nix shell=
 - =nix run=
 
-In general, the non-flakes guide only explains usage of experimental =nix=
-subcommands when there exist no other alternatives, or when the alternatives are
+In general, the non-flakes guide only explains the usage of experimental =nix=
+subcommands when there exist no other alternatives or when the alternatives are
 considered worse for new users.
 
-=nix search= simply has no good alternative within the set of non-experimental
-Nix tools, but it's too useful to not tell users about. Again, this is an
+For example, =nix search= has no alternative within the set of non-experimental
+Nix tools, and it's too helpful not to tell users about it. Again, this is an
 example of the Nix community leading users to experimental features.
 
-=nix shell= and =nix run= are shown as improved alternatives to =nix-shell=.
-=nix-shell= is a complicated tool that has been historically used for a lot of
-different purposes:
+Additionally, =nix shell= and =nix run= are shown as improved alternatives to
+=nix-shell=.  =nix-shell= is a complicated tool that has been historically used
+for a lot of different purposes:
 - debugging the build environments of packages
 - creating a developer environment for a package (=nix develop= does this
-  better, but for only for flakes)
+  better, but only for flakes)
 - entering a shell with Nix-build executables on the path (=nix shell= does this
   better)
 - running arbitrary commands with Nix-build executables on the path (=nix run=
   does this better)
 
 To cover all of these scenarios, =nix-shell= became so complex it is hard to
-explain to new users. =nix-shell= is really only best for debugging builds,
-which is beyond the scope of the documentation provided by this project.
+explain to new users. =nix-shell= is only best for debugging builds, which is
+beyond the scope of the documentation provided by this project.

doc/internal/nix-usage-flakes-optional.org

@@ -5,12 +5,12 @@ project-dependent.
 #+end_comment
 
 This project supports a still-experimental feature of Nix called /flakes/, which
-this guide shows users how to use. [[file:nix-usage-noflakes.org][Another guide]] explains how to do
-everything illustrated in this document, but without flakes.
+this guide shows users how to use. [[file:nix-usage-noflakes.org][Another guide]] explains how to do everything
+illustrated in this document, but without flakes.
 
 #+begin_quote
 *_NOTE:_* If you're new to flakes, please read the provided [[file:nix-introduction.org][supplemental
 introduction to Nix]] to understand the experimental nature of flakes and how it
-may or may not affect you. Hopefully you'll find these trade-offs acceptable so
-you can take advantage of the improved experience flakes offer.
+may or may not affect you. Hopefully, you'll find these trade-offs acceptable to
+take advantage of the improved experience flakes offer.
 #+end_quote