move resource collection to separate document

NixOS · May 19, 2022 · 69d117e · 69d117e
1 parent e6ba984
commit 69d117e
Show file tree

Hide file tree

Showing 2 changed files with 97 additions and 98 deletions.
diff --git a/README.md b/README.md
@@ -21,103 +21,7 @@ Nix has a proverbially steep learning curve.
 
 The [Nix](https://nixos.org/manual/nix/stable/)[([pkgs](https://nixos.org/manual/nixpkgs/stable)|[OS](https://nixos.org/manual/nixos/stable/))] manuals, together with the [RFCs](https://github.com/NixOS/rfcs), Eelco Dolstra’s PhD thesis [The Purely Functional Software Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf), [NixOS Wiki](https://nixos.wiki/wiki/) and [nix.dev](https://nix.dev), are the most comprehensive collection of knowledge on the design of the Nix ecosystem – except for the code base itself. But these resources are dispersed, in varying state of maintenance, do not follow a coherent structure to draw an overarching narrative, and, based on rich anecdata, overall are not very effective for onbarding.
 
-Other than just [people](https://twitter.com/stewoconnor/status/1503525768881606656?s=12) [complaining](https://news.ycombinator.com/item?id=25192287) [loudly](https://discourse.nixos.org/t/how-to-climb-up-the-learning-curve-specifically-nixpkgs-haskellpackages/8400), most recently the manuals recieved an [extensive review](https://ianthehenry.com/posts/how-to-learn-nix/) from an outside-view, exposing numerous issues with regard to structure, clarity, and level of detail.
-
-## Current state of documentation
-
-> ![](https://documentation.divio.com/_images/overview.png)
 >
-> [The documentation system](https://documentation.divio.com/), a framework to think about various types of documentation, each with their own purpose and capabilities.
-
-When viewed in the framework of [The documentation system](https://documentation.divio.com), we observe the following.
-
-The manuals appear not to be maintained in any coordinated fashion, supposedly due to their ever increasing size. They do not serve a clear-cut purpose, and are instead somewhere in between an explanation and a reference, fulfilling both roles only partially.
-
-There exist many resources showing *how to use* Nix or NixOS or interact with `nixpkgs`, some in writing, some as instructional videos.
-
-There exists an overwhelming amount of “Nix” explanations, all of which *only* refer to the Nix configuration language.
-
-There seems to exist no self-contained, complete, up-to-date **explanation** of Nix the package manager, NixOS, or `nixpkgs` with respect to fundamental operating principles, architecture and design decisions! @edolstra’s thesis is still the most comprehensive source on rationale, yet only covers Nix language and package manager in depth.
-
-Given [the thesis has been removed from the NixOS web site in 2017](https://github.com/NixOS/nixos-homepage/issues/830), we can assume that more recent Nix newcomers do not even know it exists. As the thesis is not a living document, it is necessarily outdated in some regards. It still has the most precise conceptual explanations, and presenting them in accessible form would already improve the state of affairs.
-
-<table><tr valign=top><td>
-
-### Tutorials
-
-Nix language
-- [learn Nix in Y minutes](https://learnxinyminutes.com/docs/nix/)
-- [Tour of Nix](https://nixcloud.io/tour/?id=1)
-- [Nix by example](https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55)
-- [Nix Language Overview](https://www.youtube.com/watch?v=eCapIx9heBw&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=5)
-- [Nix Pills Chapter 4](https://nixos.org/guides/nix-pills/basics-of-language.html) and [5](https://nixos.org/guides/nix-pills/functions-and-imports.html)
-
-Nixpkgs
-- [Nix Shell Overview](https://www.youtube.com/watch?v=SGekN4pDExY&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=6)
-- [Nix Fundamentals](https://www.youtube.com/watch?v=m4sv2M9jRLg)
-- [Nix Pills Chapter 8](https://nixos.org/guides/nix-pills/generic-builders.html), [9](https://nixos.org/guides/nix-pills/automatic-runtime-dependencies.html), [10](https://nixos.org/guides/nix-pills/developing-with-nix-shell.html), [12](https://nixos.org/guides/nix-pills/inputs-design-pattern.html), [13](https://nixos.org/guides/nix-pills/callpackage-design-pattern.html), [14](https://nixos.org/guides/nix-pills/override-design-pattern.html), [16](https://nixos.org/guides/nix-pills/nixpkgs-parameters.html), [17](https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html), [19](https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html), [20](https://nixos.org/guides/nix-pills/basic-dependencies-and-hooks.html)
-
-NixOS
-- [NixOS Filesystem Overview](https://www.youtube.com/watch?v=jf0nIn2oS8A&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=4)
-
-Nix package manager
-- [Nix Pills Chapter 3](https://nixos.org/guides/nix-pills/enter-environment.html), [6](https://nixos.org/guides/nix-pills/our-first-derivation.html), [7](https://nixos.org/guides/nix-pills/working-derivation.html), [11](https://nixos.org/guides/nix-pills/garbage-collector.html), [15](https://nixos.org/guides/nix-pills/nix-search-paths.html), [18](https://nixos.org/guides/nix-pills/nix-store-paths.html)
-</td>
-<td>
-
-### How-To Guides
-
-Nix language
-
-Nixpkgs
-- [NixOS Wiki FAQ](https://nixos.wiki/wiki/FAQ)
-- [nix.dev guides](https://nix.dev/)
-- [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ)
-- [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable)
-
-NixOS
-- [nix.dev guides](https://nix.dev/)
-- [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ)
-- [Nix notes](https://github.com/noteed/nix-notes)
-- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
-
-Nix package manager
-- [NixOS Wiki: Managing the Store](https://nixos.wiki/wiki/Nix_Cookbook#Managing_storage)</td></tr><tr valign=top><td>
-
-### Explanation
-
-Nix language
-
-- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
-
-Nixpkgs
-- [Nix Pills, partial](https://nixos.org/guides/nix-pills/index.html)
-
-NixOS
-
-Nix package manager
-- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)</td><td>
-
-### Reference
-
-Nix language
-- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
-- [Nix manual (writing Nix expressions)](https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html)
-- [one-page reference](https://github.com/tazjin/nix-1p)
-
-Nixpkgs
-- [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable)
-
-NixOS
-- [NixOS manual](https://nixos.org/manual/nixos/stable)
-
-Nix package manager
-- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
-- [Nix manual (command reference)](https://nixos.org/manual/nix/stable/command-ref/command-ref.html)
-</td></tr></table>
-
-
-> Note that we have significantly more how-to material than anything else, which does not show prominently in the table because is summarized in NixOS Wiki and nix.dev.
 
 There also seems to exist no birds-eye view on the larger ecosystem and the interplay of its components.
 
@@ -239,7 +143,7 @@ The Nix Book is supposed to be the living, up-to-date overview on all concepts s
 
 The main target audience are autodidacts who do not have access to hand-holding or personal training, nor possibility for learning through osmosis. It shall contain explanations of technical principles, design rationale, and architecture of all major components in the Nix ecosystem as it is today.
 
-It can mostly be based on available information; reoganized, reworded, or complemented where necessary. See the [proposed outline](#outline) and compare to current state of documentation for an impression where material can be repurposed. It should be extended with diagrams and illustrations where it would add clarity.
+It can mostly be based on available information; reoganized, reworded, or complemented where necessary. See the [proposed outline](#outline) and compare to [current state of documentation](resources.md) for an impression where material can be repurposed. It should be extended with diagrams and illustrations where it would add clarity.
 
 Hypertext allows multiple reading orders through a collection self-contained, but related units. With the right design we can offer multiple coherent access paths into conceptual knowledge; for example breadth-first, depth-first, or free link-surfing.
 
@@ -381,7 +285,7 @@ While the main goal is to fill the explanation gap, gaining an overview, buildin
 The results of sorting through and reorganizing material for the book can be made available to the general public and already help with onboarding even before the explanations fully materialize.
 
 - collect and correctly categorize
-    - similar to or based on [my initial survey](#current-state-of-documentation)
+    - similar to or based on [an initial survey of existing resources](resources.md)
     - through the lens of [Backward design](https://en.wikipedia.org/wiki/Backward_design)
         - what are learning objectives and which material achieves which?
 - add brief summaries to better orient readers

diff --git a/resources.md b/resources.md
@@ -0,0 +1,95 @@
+# Current state of documentation
+
+> ![](https://documentation.divio.com/_images/overview.png)
+>
+> [The documentation system](https://documentation.divio.com/), a framework to think about various types of documentation, each with their own purpose and capabilities.
+
+When viewed in the framework of [The documentation system](https://documentation.divio.com), we observe the following.
+
+The manuals appear not to be maintained in any coordinated fashion, supposedly due to their ever increasing size. They do not serve a clear-cut purpose, and are instead somewhere in between an explanation and a reference, fulfilling both roles only partially.
+
+There exist many resources showing *how to use* Nix or NixOS or interact with `nixpkgs`, some in writing, some as instructional videos.
+
+There exists an overwhelming amount of “Nix” explanations, all of which *only* refer to the Nix configuration language.
+
+There seems to exist no self-contained, complete, up-to-date **explanation** of Nix the package manager, NixOS, or `nixpkgs` with respect to fundamental operating principles, architecture and design decisions! @edolstra’s thesis is still the most comprehensive source on rationale, yet only covers Nix language and package manager in depth.
+
+Given [the thesis has been removed from the NixOS web site in 2017](https://github.com/NixOS/nixos-homepage/issues/830), we can assume that more recent Nix newcomers do not even know it exists. As the thesis is not a living document, it is necessarily outdated in some regards. It still has the most precise conceptual explanations, and presenting them in accessible form would already improve the state of affairs.
+
+<table><tr valign=top><td>
+
+### Tutorials
+
+Nix language
+- [learn Nix in Y minutes](https://learnxinyminutes.com/docs/nix/)
+- [Tour of Nix](https://nixcloud.io/tour/?id=1)
+- [Nix by example](https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55)
+- [Nix Language Overview](https://www.youtube.com/watch?v=eCapIx9heBw&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=5)
+- [Nix Pills Chapter 4](https://nixos.org/guides/nix-pills/basics-of-language.html) and [5](https://nixos.org/guides/nix-pills/functions-and-imports.html)
+
+Nixpkgs
+- [Nix Shell Overview](https://www.youtube.com/watch?v=SGekN4pDExY&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=6)
+- [Nix Fundamentals](https://www.youtube.com/watch?v=m4sv2M9jRLg)
+- [Nix Pills Chapter 8](https://nixos.org/guides/nix-pills/generic-builders.html), [9](https://nixos.org/guides/nix-pills/automatic-runtime-dependencies.html), [10](https://nixos.org/guides/nix-pills/developing-with-nix-shell.html), [12](https://nixos.org/guides/nix-pills/inputs-design-pattern.html), [13](https://nixos.org/guides/nix-pills/callpackage-design-pattern.html), [14](https://nixos.org/guides/nix-pills/override-design-pattern.html), [16](https://nixos.org/guides/nix-pills/nixpkgs-parameters.html), [17](https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html), [19](https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html), [20](https://nixos.org/guides/nix-pills/basic-dependencies-and-hooks.html)
+
+NixOS
+- [NixOS Filesystem Overview](https://www.youtube.com/watch?v=jf0nIn2oS8A&amp;list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&amp;index=4)
+
+Nix package manager
+- [Nix Pills Chapter 3](https://nixos.org/guides/nix-pills/enter-environment.html), [6](https://nixos.org/guides/nix-pills/our-first-derivation.html), [7](https://nixos.org/guides/nix-pills/working-derivation.html), [11](https://nixos.org/guides/nix-pills/garbage-collector.html), [15](https://nixos.org/guides/nix-pills/nix-search-paths.html), [18](https://nixos.org/guides/nix-pills/nix-store-paths.html)
+</td>
+<td>
+
+### How-To Guides
+
+Nix language
+
+Nixpkgs
+- [NixOS Wiki FAQ](https://nixos.wiki/wiki/FAQ)
+- [nix.dev guides](https://nix.dev/)
+- [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ)
+- [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable)
+
+NixOS
+- [nix.dev guides](https://nix.dev/)
+- [Jon Ringer’s videos](https://www.youtube.com/channel/UC-cY3DcYladGdFQWIKL90SQ)
+- [Nix notes](https://github.com/noteed/nix-notes)
+- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
+
+Nix package manager
+- [NixOS Wiki: Managing the Store](https://nixos.wiki/wiki/Nix_Cookbook#Managing_storage)</td></tr><tr valign=top><td>
+
+### Explanation
+
+Nix language
+
+- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
+
+Nixpkgs
+- [Nix Pills, partial](https://nixos.org/guides/nix-pills/index.html)
+
+NixOS
+
+Nix package manager
+- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)</td><td>
+
+### Reference
+
+Nix language
+- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
+- [Nix manual (writing Nix expressions)](https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html)
+- [one-page reference](https://github.com/tazjin/nix-1p)
+
+Nixpkgs
+- [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable)
+
+NixOS
+- [NixOS manual](https://nixos.org/manual/nixos/stable)
+
+Nix package manager
+- [PhD Thesis](https://edolstra.github.io/pubs/phd-thesis.pdf)
+- [Nix manual (command reference)](https://nixos.org/manual/nix/stable/command-ref/command-ref.html)
+</td></tr></table>
+
+
+> Note that we have significantly more how-to material than anything else, which does not show prominently in the table because is summarized in NixOS Wiki and nix.dev.