{"id":13838252,"url":"https://github.com/NixOS/nix-book","last_synced_at":"2025-07-10T21:32:01.068Z","repository":{"id":37709601,"uuid":"493582081","full_name":"NixOS/nix-book","owner":"NixOS","description":"Nix documentation – centralized community online learning resource for Nix","archived":true,"fork":false,"pushed_at":"2023-03-23T17:59:12.000Z","size":59,"stargazers_count":238,"open_issues_count":1,"forks_count":9,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-07-01T22:27:34.352Z","etag":null,"topics":["documentation","learning","nix"],"latest_commit_sha":null,"homepage":"https://discourse.nixos.org/t/documentation-team-flattening-the-learning-curve/20003","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NixOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"open_collective":"nixos"}},"created_at":"2022-05-18T08:49:21.000Z","updated_at":"2025-07-01T00:23:48.000Z","dependencies_parsed_at":"2022-07-22T01:32:20.518Z","dependency_job_id":null,"html_url":"https://github.com/NixOS/nix-book","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"a3b36fa16e75c12aed467c25447bfb5e2650c409"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NixOS/nix-book","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnix-book","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnix-book/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnix-book/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnix-book/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NixOS","download_url":"https://codeload.github.com/NixOS/nix-book/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnix-book/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264650201,"owners_count":23643890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","learning","nix"],"created_at":"2024-08-04T15:01:46.290Z","updated_at":"2025-07-10T21:32:01.012Z","avatar_url":"https://github.com/NixOS.png","language":null,"funding_links":["https://opencollective.com/nixos"],"categories":["Others"],"sub_categories":[],"readme":"# The Nix Book\n\n\u003e **Warning**\n\u003e This repository may eventually disappear.\n\u003e\n\u003e The [Nix documentation team][docs-team] now works on [nix.dev][nix-dev] towards the vision outlined here.\n\n[docs-team]: https://discourse.nixos.org/t/documentation-team-flattening-the-learning-curve/20003\n[nix-dev]: https://github.com/NixOS/nix.dev\n\n\n## A vision for the journey into Nix, `nixpkgs`, and NixOS\n\nThis book is supposed to fit between first impressions on the [Nix web site][nixos-org] and the reference manuals for [Nix][nix-manual], [Nixpkgs][nixpkgs-manual], [NixOS][nixos-manual].\n\n```mermaid\nflowchart\n  subgraph homepage\n\t  core --\u003e explore\n\t\tget-started --\u003e learn\n\t\texplore --\u003e |details| how-nix-works\n\t  subgraph front-page[front page]\n\t\t\tsubgraph core[core features]\n\t\t\t\tsame[always working environment, everywhere]\n\t\t\t\tpolyglot[many programming languages]\n\t\t\t\tdeploy[configure, build, deploy]\n\t\t\t\trollbacks[roll back any time]\n\t\t\t\tcommunity[global community]\n\t\t\tend\n\t\t\texamples\n\t\t\tget-started[get started]\n\t\tend\n\t\tsubgraph explore\n\t\t\tcomplete[complete dependencies]\n\t\t\treproducible[reproducible builds]\n\t\t\tcorrect[correct deployment]\n\t\t\tmultiple[multiple versions]\n\t\t\tatomic[atomic upgrades]\n\t\t\tagnostic[many programming languages]\n\t\t\tcaching[transparent caching]\n\t\t\tremote[remote builds]\n\t\t\tnixpkgs[community package collection]\n\t\t\tnixexpr[purely functional configuration language]\n\t\tend\n\t\tsubgraph learn\n\t\t\tinstall\n\t\t\tfirst-steps[first steps]\n\t\t\thow-nix-works[how nix works]\n\t  end\n  end\n\tfirst-steps --\u003e book --\u003e manuals --\u003e source\n\tbook --\u003e discussion\n\tsubgraph book[The Nix Book]\n\t\tdirection TB\n\t\tbuild --\u003e imperative-pkgs \u0026 declarative-pkgs\n\t\tdeclarative-pkgs --\u003e writing --\u003e declarative-config \u0026 dev \u0026 nixpkgs-learn\n\t\tsubgraph build[run software]\n\t\t\tdirection LR\n\t\t\tfind-pkg[find packages]\n\t\t\trun[run a program]\n\t\t\tshell[set up temporary environment]\n\t\tend\n\t\tsubgraph imperative-pkgs[imperative package management]\n\t\t\tdirection LR\n\t\t\tinstall-profile[install]\n\t\t\tupdate\n\t\t\trollback\n\t\t\tpin-packages[pin packages]\n\t\tend\n\t\tsubgraph declarative-pkgs[declarative package management]\n\t\t\tdirection LR\n\t\t\tdecl-env[reproducible environment]\n\t\t\tcompose[compose packages]\n\t\t\tadapt[adapt packages]\n\t\t\tpin-deps[pin dependencies]\n\t\t\tgc[garbage collection]\n\t\tend\n\t\tsubgraph nixpkgs-learn[package collection]\n\t\t\tdirection LR\n\t\t\tmodify[modify existing package]\n\t\t\tnewpkg[create new package]\n\t\t\tcontribute-nixpkgs[contribute to nixpkgs]\n\t\tend\n\t\tsubgraph declarative-config[declarative configuration management]\n\t\t\tdirection LR\n\t\t\tuser-env[user environments]\n\t\t\tos[operating system distribution]\n\t\t\tservices[service management]\n\t\tend\n\t\tsubgraph writing[configuration language]\n\t\t\tsyntax\n\t\t\tfunctions\n\t\t\tattrsets[attribute sets]\n\t\t\tdebugging\n\t\t\tlibrary\n\t\t\ttools[tool support]\n\t\tend\n\t\tsubgraph dev[software development]\n\t\t\tdirection LR\n\t\t\tlang-ecosystems[language ecosystems]\n\t\t\tcaching\n\t\t\tdeployment\n\t\t\tci[continuous integration]\n\t\t\tdistributed[distributed builds]\n\t\t\tcross-compilation\n\t\t\tbundling[bundling build results]\n\t\tend\n\tend\n\tsubgraph discussion\n\t\tRFCs\n\t\tpr[pull requests]\n\t\tissues\n\t\tDiscourse\n\tend\n\tsubgraph manuals\n\t\tsubgraph man-nix[Nix]\n\t\t\tcmd[command line interface]\n\t\tlang[expression language]\n\t\t\tconfig[configuration]\n\t\t\tarchitecture\n\t\tend\n\t\tman-nixpkgs[nixpkgs]\n\t\tman-nixos[NixOS]\n\tend\n\tsubgraph source[source code]\n\t\tnix-src[NixOS/nix]\n\t\tnixpkgs-src[NixOS/nixpkgs]\n\tend\n\n```\n## Contributing\n\nPlease consider [contributing to this book](CONTRIBUTING.md), especially if\n\n- you are currently learning to use Nix\n- you have experience teaching Nix\n- you are a domain expert using Nix to solve specific problems.\n\n[nixos-org]: https://nixos.org\n[nix-manual]: https://nixos.org/manual/nix/stable/\n[nixpkgs-manual]: https://nixos.org/manual/nixpkgs/stable/\n[nixos-manual]: https://nixos.org/manual/nixos/stable/\n\n# Motivation\n\nNix has a proverbially steep learning curve.\n\n\u003e ![](https://discourse.nixos.org/uploads/default/original/2X/f/fef4e7f73fbca41179060500174f1448d16fb8c9.jpeg)\n\u003e\n\u003e [Posted by nixinator](https://discourse.nixos.org/t/probably-the-best-lecture-of-nix-fundamentals-on-the-internet/9893) on NixOS Discourse\n\nThe [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.\nBut 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, community folklore, and the [2022 Nix survey](https://discourse.nixos.org/t/2022-nix-survey-results/18983), overall are not very effective for onbarding:\n\n\u003e ### Documentation, Documentation, Documentation\n\u003e\n\u003e Documentation (once again) came up universally across almost all respondents.\n  Key asks in this area revolved around three aspects - onboarding, unblocking and centralization.\n\u003e\n\u003e - Onboarding - A majority of respondents highlighted trouble in the onboarding phase.\n    The lack of new user documentation meant users have a tough time understanding how to onboard, following the first few steps, understanding best practices and finding general FAQs.\n\u003e - Unblocking - Respondents heavily emphasized the need for better documentation in the realm of tutorials/guides/examples that can help serve in unblocking themselves.\n\u003e - Centralization - Many were frustrated with the time it took to locate relevant documentation.\n    Searching for answers took too long and invariably led them to various websites, github repos, and videos - often requiring multiple resources to address the same issue.\n\nThere also seems to exist no birds-eye view on the larger ecosystem and the interplay of its components.\n\n\u003e ![](https://discourse.nixos.org/uploads/default/original/2X/b/b0c3368ce1a5b94b061184f98a8db49bfd209c51.png)\n\u003e\n\u003e Own contribution; does not cover topics such as deployment or support tooling.\n\nMeanwhile, complexity is ever growing with new features, and disparity between what is actually explained and what people use in the field continuously increases.\n\nNix becomes harder to learn every day.\n\n# Project proposal\n\nThe goal of the following proposal is to make Nix the package manager as well as its sourrounding tools more accessible to Nix beginners, and enabling expert users to become effective contributors or maintainers.\n\n## Write and publish **The Nix Book**\n\nThe Nix Book is supposed to be the living, up-to-date overview on all concepts surrounding Nix.\n\nThe 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.\n\nIt can mostly be based on available information; reoganized, reworded, or complemented where necessary. See the [proposed outline](contents/README.md) 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.\n\nHypertext 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.\n\nIdeally there should be usability tests with dedicated or in-line surveys that allow collecting feedback and checking if set learning goals have been met.\n\n## Rework the Nix manual\n\nWhile the main goal is to fill the explanation gap, gaining an overview, building detailed understanding, collecting and restructuring content is already part of the task. Some of that work could therefore entail overhauling the Nix manual to better fit into the new narrative. Nix the package manager is the core component of the ecosystem and also has the smallest single manual, most amenable to structural change.\n\n- develop a strategy to reposition the manual as purely reference material for Nix the package manager and the Nix expression language\n    - place the purpose statement prominently\n        - within manual itself\n        - in contribution guidelines\n    - find new places for material that does not belong any more\n    - @edolstra suggests to remove (or adopt in The Nix Book) the following sections\n        - Introduction\n        - Quick Start\n        - Package Management\n        - The introductory parts of \"Writing Nix Expressions\"\n        - Glossary\n- triage, collect, or document, and keep track of all existing issues\n    - conduct, lead, and coordinate attacking the issues by (however determined) priority\n    - invite and enable domain experts and volunteers\n        - help with merging their contributions\n- develop schemes to improve navigation and discoverability\n    - links from terms to definitions\n    - links to source code\n\n## Improve discoverability of existing learning material\n\nThe 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.\n\n- collect and correctly categorize\n    - similar to or based on [an initial survey of existing resources](resources.md)\n    - through the lens of [Backward design](https://en.wikipedia.org/wiki/Backward_design)\n        - what are learning objectives and which material achieves which?\n- add brief summaries to better orient readers\n- rework navigation of learning on [nixos.org][nixos-org] to incorporate the new structure\n    - lead readers and contributors to the right places for their types of questions\n\n## How is success defined and measured?\n\nIn broad terms, The Nix Book and changes to documentation and web site should measurably increase probability of successful onboarding and decrease time to obtain some well-defined skill set.\n\nPart of the tasks would be to define the learning goals, develop test questions to assess to what degree they were reached, and put up questionnaire forms in each chapter to capture the answers.\n\nSince there are no prior metrics, setting up a preliminary questionnaire should be the first publicly visible part, presented for tutorials on the [learning page](https://nixos.org/learn), [recurring community surveys](https://discourse.nixos.org/t/nix-community-survey-2022-update/18733), and possibly relevant sections of the manuals.\n\nResults should help direct further work, and help answer questions such as:\n\n- Which questions do newcomers ask most, and do they find satisfactory answers consistent with best practice?\n- Which material should we add?\n- How should we reorganize existing material?\n- How should we improve existing material?\n\nAs a consequence we should observe influx of new regular users and contributors to `nixpkgs`, NixOS, and eventually Nix proper. We currently cannot measure this. Unfortunately we do not gather community metrics, and this is out of this project's scope.\n\n# License and Support\n\n[![License: CC BY-SA 4.0][cc-by-sa-button]][cc-by-sa]\nThis work is licensed under a [Creative Commons Attribution-ShareAlike 4.0][cc-by-sa] International License.\n\nThis project is sponsored by [Tweag][tweag].\n\n[cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/\n[cc-by-sa-button]: https://licensebuttons.net/l/by-sa/4.0/80x15.png\n[tweag]: https://www.tweag.io\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNixOS%2Fnix-book","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNixOS%2Fnix-book","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNixOS%2Fnix-book/lists"}